Package: webcam
WebcamWebcamis a simple, yet powerful Python library that brings advanced webcam handling to your projects. Implemented under the same interface thancv2.VideoCapture, it heavily simplifieshigh-levelframe manipulation, providing an intuitive and versatile way to handle video input from a range of sources likewebcams,IP cameras, andvideo files.WithWebcam, you can easily control theframe size, adjust theaspect ratio, and applyPerspective Transformsto thevideo stream, all while preserving crucial information aboutpixel originandmagnification.Furthermore, it includes a unique aspect that allows users to authenticallymirror webcam inputusingvideo files. It ensures that the frame accessed at any particular moment matches the exact frame you'd encounter in areal-time webcam stream, making it a valuable tool for testing and development.Designed forsimplicityanduser-friendliness,Webcamprovides advanced features without compromisingease of use. This allows you to channel your efforts into developing your application, instead of wrestling with webcam control and frame manipulation details..Advanced FunctionalityWebcamshowcases a rich set of features, advancing beyond fundamental webcam manipulation to offer a higher degree of control and flexibility:Enhanced Input Sources:Webcamseamlessly handles all input types thatOpenCVaccepts, but with added versatility. Includingwebcams,IP cameras(using RTSP URLs), andvideo files.Customizable Frame Configuration: WithWebcam, you can define the specificframe sizeand manageaspect ratiochanges when the camera's native resolution differs. Keep the widest field of view by setting just one dimension, or set both and decide betweencenter croppingorresizing(sacrificing aspect ratio).Perspective Transform: Initialize theWebcamobject with aHomography Matrixto maintain consistent perspective correction in every frame, while keeping the specifiedframe size.  If the perspective is deformed, you have the choice tocropthe frame, removing black borders, or display the entire trapezoid to avoid losing any information.Reversibility:Webcamcan easily retrieveoriginal coordinatesandpixel magnificationfor any point or section of the image. This is a valuable feature forComputer Vision Engineersneeding to perform calculations based on theraw camera sensor data.Background Reading: Enhances performance by reading frames in a background thread, with an option to limit the frame rate.Webcam Input Emulation: You can usevideo filesto accuratelyemulate webcam input. The frame you access at any instant will match the one from areal-time webcam streamat the same time. Especially handy for testing and development scenarios.Iterator and Batch Processing:Webcamoffers an iterator for simplified camera frame reading, with optional batch yielding for efficient data handling.Balancing simplicity and advanced functionality, Webcam is an efficient, flexible tool for webcam integration.InstallationYou can installWebcamwithpipinstallwebcamUsageReading a video stream is as simple as iterating over the definedwebcamobject.fromwebcamimportWebcam# Define a simple webcam object that will get video stream from webcam (src=0),#  with a frame width of 640 (auto setting heigth to keep original aspect ratio)webcam=Webcam(src=0,w=640)print(f"Frame size:{webcam.w}x{webcam.h})forframeinwebcam:# Show the frames in a cv2 windowcv2.imshow('Webcam Frame',cv2.cvtColor(frame,cv2.COLOR_RGB2BGR))# Break the loop if the user presses the 'q' keyifcv2.waitKey(1)&0xFF==ord('q'):break>>>Framesize:360x640Fitting to a strict frame sizeSometimes, yourAppsorComputer Vision Modelsmight need specific frame sizes that don't align with your video source's resolution.Webcamfrees the user of having to deal with these frame resize details, especially when there's a discrepancy in the aspect ratio between the input and output.importosfromwebcamimportWebcam# Let's use a video as a source instead of webcamvideo_source=os.path.join('resources','test_video.mp4')# Set an expected width and height, defining that "if aspect ratio differs", center crop the image.no_deformation=Webcam(src=video_source,w=640,h=640,on_aspect_ratio_lost='crop')# Replicate the situation, but defining that, "if aspect ratio differs", resize it, accepting the produced deformation.deformation=Webcam(src=video_source,w=640,h=640,on_aspect_ratio_lost='resize')# ---------------------------------------------------------------------------------------------------# Print the original video resolution (output resolution will be 640 x 640 as specified)print(f"Original WxH:{no_deformation.raw_w}x{no_deformation.raw_h}\n")# Print the magnification in both cases (Cropped one will have a higher magnification on the input's shortest axis)print(f"Resize WxH Magnification:{deformation.pixel_magnification_w}x{deformation.pixel_magnification_h}")print(f"Center Crop WxH Magnification:{no_deformation.pixel_magnification_w}x{no_deformation.pixel_magnification_h}")# Read the frames just as you would do it on OpenCVgrabbed,non_deformed_frame=no_deformation.read()grabbed,deformed_frame=deformation.read()OriginalWxH:1280x720ResizeWxHMagnification:0.50x0.89
CenterCropWxHMagnification:0.89x0.89Input Frame (1280x720)Resized (640x640)Center Crop (640x640)Applying Perspective CorrectionsYou can setupHomography Matricesto automatically applyperspective transforms. Wether if you apply them or not, you can keep the track of the origin of every coordinate in the raw sensor image.fromwebcamimportWebcam# Build an homography matrix that modifies the image perspectivehomography_matrix=[[1.,0.1,0.],[0.1,1.,0.],[0.0002,-0.0001,1.]]# Build a webcam object passing this homography matrix (let's set a fixed height and let it decide width).full_perspective=Webcam(src=video_source,h=640,homography_matrix=homography_matrix,crop_on_warping=False)no_borders=Webcam(src=video_source,h=640,homography_matrix=homography_matrix,crop_on_warping=True)# ---------------------------------------------------------------------------------------------------# Let's calculate the origin of some coordinates in the raw input resolution (Note it expects a batch).full_pers_x,full_pers_y=full_perspective.output_space_points_to_input_space(points_xy=((150,225),))[0]no_borders_x,no_borders_y=no_borders.output_space_points_to_input_space(points_xy=((625,200),))[0]# Let's calculate the precise pixel magnification of two coords in an image. As perspective deformations#  does not produce homogeneus magnifications as would happen when only resizes and/or crops are appliedno_borders_h_left,no_borders_w_left=no_borders.get_magnification_hw(x=150,y=225)no_borders_h_right,no_borders_w_right=no_borders.get_magnification_hw(x=600,y=225)print(f"Maginfication WxH at (150, 225):{no_borders_w_left}x{no_borders_h_left}")print(f"Maginfication WxH at (600, 225):{no_borders_w_right}x{no_borders_h_right}\n")print(f"Full Perspective: (150, 225) came from ({full_pers_x},{full_pers_y})")print(f"Cropped Perspective: (625, 200) came from ({no_borders_x},{no_borders_y})")>>>MaginficationWxHat(150,225):1.064x0.999
>>>MaginficationWxHat(600,225):0.984x0.842

>>>FullPerspective:(150,225)camefrom(156.63,258.30)>>>CroppedPerspective:(625,200)camefrom(733.69,255.35)Input Frame (1280x720)Full Perspective (943x640)Hidding Borders (980x640)Limiting maximum frame rateSometimes, you'll need to simulate a fixed frame rate (for example, when you want to write video files). For these cases, you can limit the maximum frame rate. It will transform the frame retrieval in a blockant operation, making sure that you don't surpass the specified frame rate.fromwebcamimportWebcam# Build a webcam object that will limit frame rate to a maximum of 12 fps (get it as BGR).webcam_12_fps=Webcam(src=video_source,max_frame_rate=12,as_bgr=True,simulate_webcam=True)# ---------------------------------------------------------------------------------------------------# Write the video on a .mp4 file that requires a fixed pre-known frame ratevideo_writer=cv2.VideoWriter(filename='test.mp4',fourcc=cv2.VideoWriter_fourcc(*'mp4v'),fps=12,frameSize=(webcam_12_fps.w,webcam_12_fps.h))forframeinwebcam_12_fps:video_writer.write(frame)video_writer.release()5 FPS (1280x720)12 FPS (1280x720)