Video System

Provides the main VideoSystem class that contains methods for setting up, running, and tearing down interactions between camera interfaces and video saver instances.

All user-oriented functionality of this library is available through the public methods of the VideoSystem class.

class ataraxis_video_system.video_system.VideoSystem(system_id, data_logger, output_directory, camera_interface=CameraInterfaces.OPENCV, camera_index=0, display_frame_rate=None, frame_width=None, frame_height=None, frame_rate=None, gpu=-1, video_encoder=VideoEncoders.H265, encoder_speed_preset=EncoderSpeedPresets.SLOW, output_pixel_format=OutputPixelFormats.YUV444, quantization_parameter=15, *, color=None)

Bases: object

Acquires, displays, and saves camera frames to disk using the requested camera interface and video saver.

This class controls the runtime of a camera interface and a video saver running in independent processes and efficiently moves the frames acquired by the camera to the saver process.

Notes

This class reserves up to two logical cores to support the producer (camera interface) and consumer (video saver) processes. Additionally, it reserves a variable portion of the RAM to buffer the frames as they are moved from the producer to the consumer.

Video saving relies on the third-party software ‘FFMPEG’ to encode the video frames as an .mp4 file. See https://www.ffmpeg.org/download.html for more information on installing the library.

Parameters:

• system_id (uint8) – The unique value to use for identifying the VideoSystem instance in all output streams (log files, terminal messages, video files).

• data_logger (DataLogger) – An initialized DataLogger instance used to log the timestamps for all frames saved by this VideoSystem instance.

• output_directory (Path | None) – The path to the output directory where to store the acquired frames as the .mp4 video file. Setting this argument to None disabled video saving functionality.

• camera_interface (CameraInterfaces | str, default: <CameraInterfaces.OPENCV: 'opencv'>) – The interface to use for working with the camera hardware. Must be one of the CameraInterfaces enumeration members.

• camera_index (int, default: 0) – The index of the camera in the list of all cameras discoverable by the chosen interface, e.g.: 0 for the first available camera, 1 for the second, etc. This specifies the camera hardware the instance should interface with at runtime.

• display_frame_rate (int | None, default: None) – Determines the frame rate at which to display the acquired frames to the user. Setting this argument to None (default) disables frame display functionality. Note, frame displaying is not supported on some macOS versions.

• frame_rate (int | None, default: None) – The desired rate, in frames per second, at which to capture the frames. Note; whether the requested rate is attainable depends on the hardware capabilities of the camera and the communication interface. If this argument is not explicitly provided, the instance uses the default frame rate of the managed camera.

• frame_width (int | None, default: None) – The desired width of the acquired frames, in pixels. Note; the requested width must be compatible with the range of frame dimensions supported by the camera hardware. If this argument is not explicitly provided, the instance uses the default frame width of the managed camera.

• frame_height (int | None, default: None) – Same as ‘frame_width’, but specifies the desired height of the acquired frames, in pixels. If this argument is not explicitly provided, the instance uses the default frame height of the managed camera.

• color (bool | None, default: None) – Specifies whether the camera acquires colored or monochrome images. This determines how to store the acquired frames. Colored frames are saved using the ‘BGR’ channel order, monochrome images are reduced to a single-channel format. This argument is only used by the OpenCV and Mock camera interfaces, the Harvesters interface infers this information directly from the camera’s configuration.

• gpu (int, default: -1) – The index of the GPU to use for video encoding. Setting this argument to a value of -1 (default) configures the instance to use the CPU for encoding. Valid GPU indices can be obtained from the ‘nvidia-smi’ terminal command.

• video_encoder (VideoEncoders | str, default: <VideoEncoders.H265: 'H265'>) – The encoder to use for generating the video file. Must be one of the valid VideoEncoders enumeration members.

• encoder_speed_preset (EncoderSpeedPresets | int, default: <EncoderSpeedPresets.SLOW: 5>) – The encoding speed preset to use for generating the video file. Must be one of the valid EncoderSpeedPresets enumeration members.

• output_pixel_format (OutputPixelFormats | str, default: <OutputPixelFormats.YUV444: 'yuv444p'>) – The pixel format to be used by the output video file. Must be one of the valid OutputPixelFormats enumeration members.

• quantization_parameter (int, default: 15) – The integer value to use for the ‘quantization parameter’ of the encoder. This determines how much information to discard from each encoded frame. Lower values produce better video quality at the expense of longer processing time and larger file size: 0 is best, 51 is worst. Note, the default value is calibrated for the H265 encoder and is likely too low for the H264 encoder.

_started

Tracks whether the system is currently running (has active subprocesses).

_mp_manager

Stores the SyncManager instance used to control the multiprocessing assets (Queue and Lock instances).

_system_id

Stores the unique identifier code of the VideoSystem instance.

_output_file

Stores the path to the output .mp4 video file to be generated at runtime or None, if the instance is not configured to save acquired camera frames.

_camera

Stores the camera interface class instance used to interface with the camera hardware at runtime.

_saver

Stores the video saver instance used to save the acquired camera frames or None, if the instance is not configured to save acquired camera frames.

_logger_queue

Stores the multiprocessing Queue instance used to buffer frame acquisition timestamp data to the logger process.

_saver_queue

Stores the multiprocessing Queue instance used to buffer and pipe acquired frames from the camera (producer) process to the video saver (consumer) process.

_terminator_array

Stores the SharedMemoryArray instance used to manage the runtime behavior of the producer and consumer processes.

_producer_process

A process that acquires camera frames using the managed camera interface.

_consumer_process

A process that saves the acquired frames using managed video saver.

_watchdog_thread

A thread used to monitor the runtime status of the remote consumer and producer processes.

Raises:

• TypeError – If any of the provided arguments has an invalid type.

• ValueError – If any of the provided arguments has an invalid value.

• RuntimeError – If the host system does not have access to FFMPEG or Nvidia GPU (when the instance is configured to use hardware encoding).

start()

Starts the instance’s producer (camera interface) and consumer (video saver) processes and begins acquiring camera frames.

Return type:

None

Notes

Calling this method does not enable saving camera frames to non-volatile memory. To enable saving camera frames, call the start_frame_saving() method.

Raises:

RuntimeError – If starting the consumer or producer processes stalls or fails.

start_frame_saving()

Enables saving acquired camera frames to disk as an .mp4 video file.

Return type:

None

property started: bool

Returns True if the system has been started and has active producer and (optionally) consumer processes.

stop()

Stops the instance’s producer (camera interface) and consumer (video saver) processes and releases all reserved resources.

Return type:

None

Notes

The consumer process is kept alive until all frames buffered to the saver_queue are saved. However, if the saver_queue does not become empty within 10 minutes from calling this method, it forcibly terminates the consumer process and discards any unprocessed data.

stop_frame_saving()

Disables saving acquired camera frames to disk as an .mp4 video file.

Return type:

None

Notes

Calling this method does not stop the frame acquisition process. It only prevents the acquired frames from being sent to the consumer process, which prevents them from being saved to disk.

property system_id: uint8

Returns the unique identifier code assigned to the VideoSystem instance.

property video_file_path: Path | None

Returns the path to the output video file if the instance is configured to save acquired camera frames and None otherwise.

ataraxis_video_system.video_system.extract_logged_camera_timestamps(log_path, n_workers=-1)

Extracts the video camera frame acquisition timestamps from the target .npz log file generated by a VideoSystem instance during runtime.

This function reads the ‘.npz’ archive generated by the DataLogger’s assemble_log_archives() method for a VideoSystem instance and, if the system saved any frames acquired by the managed camera, extracts the tuple of frame timestamps. The order of timestamps in the tuple is sequential and matches the order in which the frames were appended to the .mp4 video file.

Notes

The timestamps are given as microseconds elapsed since the UTC epoch onset.

If the target .npz archive contains fewer than 2000 messages, the processing is carried out sequentially regardless of the specified worker-count.

Parameters:

• log_path (Path) – The path to the .npz log file that stores the logged data generated by the VideoSystem instance during runtime.

• n_workers (int, default: -1) – The number of parallel worker processes (CPU cores) to use for processing. Setting this to a value below 1 uses all available CPU cores. Setting this to a value of 1 conducts the processing sequentially.

Return type:

tuple[uint64, ...]

Returns:

A tuple that stores the frame acquisition timestamps. Each timestamp is stored as the number of microseconds elapsed since the UTC epoch onset.

Raises:

ValueError – If the target .npz archive does not exist.

Camera

Provides a unified API that allows other library modules to interface with any supported camera hardware.

Primarily, these interfaces abstract the necessary procedures to connect to the camera and continuously grab the acquired frames.

class ataraxis_video_system.camera.CameraInformation(camera_index, interface, frame_width, frame_height, acquisition_frame_rate, serial_number=None, model=None)

Bases: object

Stores descriptive information about a camera discoverable through OpenCV or Harvesters libraries.

acquisition_frame_rate: int

The frame rate at which the camera acquires frames, in frames per second.

camera_index: int

The index of the camera in the list of all cameras discoverable through the evaluated interface (OpenCV or Harvesters).

frame_height: int

The height of the frames acquired by the camera, in pixels.

frame_width: int

The width of the frames acquired by the camera, in pixels.

interface: CameraInterfaces | str

The interface that discovered the camera.

model: str | None = None

Only for Harvesters-discoverable cameras. Contains the camera’s model name.

serial_number: str | None = None

Only for Harvesters-discoverable cameras. Contains the camera’s serial number.

class ataraxis_video_system.camera.CameraInterfaces(*values)

Bases: StrEnum

Specifies the supported camera interface backends compatible with the VideoSystem class.

HARVESTERS = 'harvesters'

This is the preferred backend for all cameras that support the GeniCam standard, which includes most scientific and industrial machine-vision cameras. This backend is based on the ‘Harvesters’ library and works with all GeniCam-compatible interfaces (USB, Ethernet, PCIE).

MOCK = 'mock'

This backend is used exclusively for internal library testing and should not be used in production projects.

OPENCV = 'opencv'

This is the backend used for all cameras that do not support the GeniCam standard. This backend is based on the ‘OpenCV’ library and primarily works for consumer-grade cameras that use the USB interface.

class ataraxis_video_system.camera.HarvestersCamera(system_id, camera_index=0, frame_rate=None, frame_width=None, frame_height=None)

Bases: object

Interfaces with the specified GeniCam-compatible camera hardware to acquire frame data.

Notes

This class should not be initialized manually! Use the VideoSystem’s add_camera() method to create all camera interface instances.

Parameters:

• system_id (int) – The unique identifier code of the VideoSystem instance that uses this camera interface.

• camera_index (int, default: 0) – The index of the camera in the list of all cameras discoverable by Harvesters, e.g.: 0 for the first available camera, 1 for the second, etc. This specifies the camera hardware the instance should interface with at runtime.

• frame_rate (int | None, default: None) – The desired rate, in frames per second, at which to capture the data. Note; whether the requested rate is attainable depends on the hardware capabilities of the camera and the communication interface. If this argument is not explicitly provided, the instance uses the default frame rate of the connected camera.

• frame_width (int | None, default: None) – The desired width of the acquired frames, in pixels. Note; the requested width must be compatible with the range of frame dimensions supported by the camera hardware. If this argument is not explicitly provided, the instance uses the default frame width of the connected camera.

• frame_height (int | None, default: None) – Same as ‘frame_width’, but specifies the desired height of the acquired frames, in pixels. If this argument is not explicitly provided, the instance uses the default frame height of the connected camera.

_system_id

Stores the unique identifier code of the VideoSystem instance that uses this camera interface.

_camera_index

Stores the index of the camera hardware in the list of all Harvesters-discoverable cameras connected to the host-machine.

_frame_rate

Stores the camera’s frame acquisition rate.

_frame_width

Stores the width of the camera’s frames.

_frame_height

Stores the height of the camera’s frames.

_harvester

Stores the Harvester interface object that discovers and manages the list of accessible GenTL cameras.

_camera

Stores the Harvesters ImageAcquirer object that interfaces with the camera.

_color

Tracks whether the frames are acquired using a monochrome or a colored data format.

connect()

Connects to the managed camera hardware.

Return type:

None

disconnect()

Disconnects from the managed camera hardware.

Return type:

None

property frame_height: int

Returns the height of the acquired frames, in pixels.

property frame_rate: int

Returns the acquisition rate of the camera, in frames per second (fps).

property frame_width: int

Returns the width of the acquired frames, in pixels.

grab_frame()

Grabs the first available frame from the managed camera’s acquisition buffer.

This method has to be called repeatedly (cyclically) to fetch the newly acquired frames from the camera.

Notes

The first time this method is called, the camera initializes frame acquisition, which is carried out asynchronously. The acquired frames are temporarily stored in the camera’s circular buffer until they are fetched by this method.

Due to the initial setup of the buffering procedure, the first call to this method incurs a significant delay.

Return type:

ndarray[tuple[Any, ...], dtype[integer[Any]]]

Returns:

A NumPy array that stores the frame data. Depending on whether the camera acquires colored or monochrome images, the returned arrays have the shape (height, width, channels) or (height, width). Color data uses the BGR channel order.

Raises:

• ConnectionError – If the instance is not connected to the camera hardware.

• BrokenPipeError – If the instance fails to fetch a frame from the connected camera hardware.

• ValueError – If the acquired frame data uses an unsupported data (color) format.

property is_acquiring: bool

Returns True if the camera is currently acquiring video frames.

property is_connected: bool

Returns True if the instance is connected to the camera hardware.

property pixel_color_format: InputPixelFormats

Returns the pixel color format of the acquired frames.

class ataraxis_video_system.camera.MockCamera(system_id, frame_rate=None, frame_width=None, frame_height=None, *, color=True)

Bases: object

Simulates (mocks) the behavior of the OpenCVCamera and HarvestersCamera classes without the need to interface with a physical camera.

This class is primarily used to test the VideoSystem class functionality. The class fully mimics the behavior of other camera interface classes but does not establish a physical connection with any camera hardware.

Notes

This class should not be initialized manually! Use the VideoSystem’s add_camera() method to create all camera interface instances.

Parameters:

• system_id (int) – The unique identifier code of the VideoSystem instance that uses this camera interface.

• frame_rate (int | None, default: None) – The simulated frame acquisition rate of the camera, in frames per second.

• frame_width (int | None, default: None) – The simulated camera frame width, in pixels.

• frame_height (int | None, default: None) – The simulated camera frame height, in pixels.

• color (bool, default: True) – The simulated camera frame color mode. If True, the frames are generated using the BGR color mode. If False, the frames are generated using the grayscale (monochrome) color mode.

_system_id

Stores the unique identifier code of the VideoSystem instance that uses this camera interface.

_color

Determines whether to simulate monochrome or RGB frame images.

_camera

Tracks whether the camera is ‘connected’.

_frame_rate

Stores the camera’s frame acquisition rate.

_frame_width

Stores the width of the camera’s frames.

_frame_height

Stores the height of the camera’s frames.

_acquiring

Tracks whether the camera is currently acquiring video frames.

_frames

Stores the pool of pre-generated frame images used to simulate camera frame acquisition.

_current_frame_index

The index of the currently evaluated frame in the pre-generated frame pool buffer. This is used to simulate the behavior of the cyclic buffer used by physical cameras.

_timer

After the camera is ‘connected’, this attribute is used to store the timer class that controls the simulated camera’s frame rate.

_time_between_frames

Stores the number of milliseconds that has to pass between two consecutive frame acquisitions, used to simulate a physical camera’s frame rate.

connect()

Simulates connecting to the camera hardware.

Return type:

None

disconnect()

Simulates disconnecting from the camera hardware.

Return type:

None

property frame_height: int

Returns the height of the acquired frames, in pixels.

property frame_pool: tuple[ndarray[tuple[Any, ...], dtype[uint8]], ...]

Returns the pool of camera frames sampled by the grab_frame() method.

property frame_rate: int

Returns the acquisition rate of the camera, in frames per second (fps).

property frame_width: int

Returns the width of the acquired frames, in pixels.

grab_frame()

Grabs the first available frame from the managed camera’s acquisition buffer.

This method has to be called repeatedly (cyclically) to fetch the newly acquired frames from the camera.

Return type:

ndarray[tuple[Any, ...], dtype[uint8]]

Returns:

A NumPy array that stores the frame data. Depending on whether the camera acquires colored or monochrome images, the returned arrays have the shape (height, width, channels) or (height, width). Color data uses the BGR channel order.

Raises:

RuntimeError – If the method is called for a class not currently ‘connected’ to a camera.

property is_acquiring: bool

Returns True if the camera is currently ‘acquiring’ video frames.

property is_connected: bool

Returns True if the instance is ‘connected’ to the camera hardware.

property pixel_color_format: InputPixelFormats

Returns the pixel color format of the acquired frames.

class ataraxis_video_system.camera.OpenCVCamera(system_id, camera_index=0, frame_rate=None, frame_width=None, frame_height=None, *, color=True)

Bases: object

Interfaces with the specified OpenCV-compatible camera hardware to acquire frame data.

Notes

This class should not be initialized manually! Use the VideoSystem’s add_camera() method to create all camera interface instances.

Parameters:

• system_id (int) – The unique identifier code of the VideoSystem instance that uses this camera interface.

• color (bool, default: True) – Specifies whether the camera acquires colored or monochrome images. This determines how to store the acquired frames. Colored frames are saved using the ‘BGR’ channel order, monochrome images are reduced to a single-channel format.

• camera_index (int, default: 0) – The index of the camera in the list of all cameras discoverable by OpenCV, e.g.: 0 for the first available camera, 1 for the second, etc. This specifies the camera hardware the instance should interface with at runtime.

• frame_rate (int | None, default: None) – The desired rate, in frames per second, at which to capture the data. Note; whether the requested rate is attainable depends on the hardware capabilities of the camera and the communication interface. If this argument is not explicitly provided, the instance uses the default frame rate of the connected camera.

• frame_width (int | None, default: None) – The desired width of the acquired frames, in pixels. Note; the requested width must be compatible with the range of frame dimensions supported by the camera hardware. If this argument is not explicitly provided, the instance uses the default frame width of the connected camera.

• frame_height (int | None, default: None) – Same as ‘frame_width’, but specifies the desired height of the acquired frames, in pixels. If this argument is not explicitly provided, the instance uses the default frame height of the connected camera.

_system_id

Stores the unique identifier code of the VideoSystem instance that uses this camera interface.

_color

Specifies whether the camera acquires colored or monochrome images.

_camera_index

Stores the index of the camera hardware in the list of all OpenCV-discoverable cameras connected to the host-machine.

_frame_rate

Stores the camera’s frame acquisition rate.

_frame_width

Stores the width of the camera’s frames.

_frame_height

Stores the height of the camera’s frames.

_camera

Stores the OpenCV VideoCapture object that interfaces with the camera.

_acquiring

Tracks whether the camera is currently acquiring frames.

connect()

Connects to the managed camera hardware.

Raises:

ValueError – If the instance is configured to override hardware-defined acquisition parameters and the camera rejects the user-defined frame height, width, or acquisition rate parameters.

Return type:

None

disconnect()

Disconnects from the managed camera hardware.

Return type:

None

property frame_height: int

Returns the height of the acquired frames, in pixels.

property frame_rate: int

Returns the acquisition rate of the camera, in frames per second (fps).

property frame_width: int

Returns the width of the acquired frames, in pixels.

grab_frame()

Grabs the first available frame from the managed camera’s acquisition buffer.

This method has to be called repeatedly (cyclically) to fetch the newly acquired frames from the camera.

Notes

The first time this method is called, the camera initializes frame acquisition, which is carried out asynchronously. If the camera supports buffering, it continuously saves the frames into its circular buffer. If the camera does not support buffering, the frame data must be fetched before the camera acquires the next frame to prevent frame loss.

Due to the initial setup of the buffering procedure, the first call to this method incurs a significant delay.

Return type:

ndarray[tuple[Any, ...], dtype[floating[Any] | integer[Any]]]

Returns:

A NumPy array that stores the frame data. Depending on whether the camera acquires colored or monochrome images, the returned arrays have the shape (height, width, channels) or (height, width). Color data uses the BGR channel order.

Raises:

• ConnectionError – If the instance is not connected to the camera hardware.

• BrokenPipeError – If the instance fails to fetch a frame from the connected camera hardware.

property is_acquiring: bool

Returns True if the camera is currently acquiring video frames.

property is_connected: bool

Returns True if the instance is connected to the camera hardware.

property pixel_color_format: InputPixelFormats

Returns the pixel color format of the acquired frames.

ataraxis_video_system.camera.add_cti_file(cti_path)

Configures the ‘harvesters’ camera interface to use the provided .cti file during all future runtimes.

The ‘harvesters’ camera interface requires the GenTL Producer interface (.cti) file to discover and interface with compatible GenTL devices (cameras). This function configures the local machine to use the specified .cti file for all future runtimes that use the ‘harvesters’ camera interface.

Notes

The path to the .cti file is stored inside the user’s data directory, so that it can be reused between library calls.

Parameters:

cti_path (Path) – The path to the CTI file that provides the GenTL Producer interface. It is recommended to use the file supplied by the camera vendor, but a general Producer, such as mvImpactAcquire, is also acceptable. See https://github.com/genicam/harvesters/blob/master/docs/INSTALL.rst for more details.

Return type:

None

ataraxis_video_system.camera.check_cti_file()

Checks whether the library is configured to use a GenTL Producer interface (.cti) file.

The ‘harvesters’ camera interface requires the GenTL Producer interface (.cti) file to discover and interface with compatible GenTL devices (cameras). This function checks if a valid .cti file path has been configured and returns the path if it exists.

Return type:

Path | None

Returns:

The Path to the configured .cti file if one exists and is valid, or None otherwise.

ataraxis_video_system.camera.discover_camera_ids()

Discovers and reports the identifier (indices) and descriptive information about all accessible cameras.

This function discovers cameras through both OpenCV and Harvesters interfaces and returns a combined tuple of CameraInformation instances. OpenCV cameras are discovered first, followed by Harvesters cameras (if a CTI file has been configured).

Notes

For OpenCV cameras, it is impossible to retrieve serial numbers or camera models. It is advised to test each discovered OpenCV camera with the ‘axvs run’ CLI command to identify the mapping between the discovered indices and physical cameras.

For Harvesters cameras, this function requires a valid CTI file to be configured via the add_cti_file() function or the ‘axvs cti’ CLI command. If no CTI file is configured, Harvesters camera discovery is skipped.

Return type:

tuple[CameraInformation, ...]

Returns:

A tuple of CameraInformation instances for all discovered cameras from both interfaces.

Saver

Provides a unified API that allows other library modules to save acquired camera frames via the FFMPEG library.

Primarily, this module abstracts the configuration and flow control steps typically involved in saving acquired camera frames as video files in real time.

class ataraxis_video_system.saver.EncoderSpeedPresets(*values)

Bases: IntEnum

Stores the supported video encoding speed presets used when saving camera frames as videos via VideoSaver instances.

Generally, the faster the encoding speed, the lower is the resultant video quality.

Notes

It is impossible to perfectly match the encoding presets for the CPU and GPU encoders. The scale defined in this enumeration represents the best-effort to align the preset scale for the two encoders.

FAST = 3

For CPU encoders, this matches the ‘fast’ level. For GPU encoders, this matches the ‘p3’ level.

FASTER = 2

For CPU encoders, this matches the ‘faster’ level. For GPU encoders, this matches the ‘p2’ level.

FASTEST = 1

For CPU encoders, this matches the ‘veryfast’ level. For GPU encoders, this matches the ‘p1’ level.

MEDIUM = 4

For CPU encoders, this matches the ‘medium’ level. For GPU encoders, this matches the ‘p4’ level.

SLOW = 5

For CPU encoders, this matches the ‘slow’ level. For GPU encoders, this matches the ‘p5’ level.

SLOWER = 6

For CPU encoders, this matches the ‘slower’ level. For GPU encoders, this matches the ‘p6’ level.

SLOWEST = 7

For CPU encoders, this matches the ‘veryslow’ level. For GPU encoders, this matches the ‘p7’ level.

class ataraxis_video_system.saver.InputPixelFormats(*values)

Bases: StrEnum

Stores the supported camera frame data (color) formats used when saving camera frames as videos via VideoSaver instances.

BGR = 'bgr24'

The preset for color images.

MONOCHROME = 'gray'

The preset for grayscale (monochrome) images.

class ataraxis_video_system.saver.OutputPixelFormats(*values)

Bases: StrEnum

Stores the supported video color formats used when saving camera frames as videos via VideoSaver instances.

YUV420 = 'yuv420p'

The ‘standard’ video color space format that uses half-bandwidth chrominance (U/V) and full-bandwidth luminance (Y). Generally, the resultant reduction in chromatic precision is not apparent to the viewer.

YUV444 = 'yuv444p'

While still minorly reducing the chromatic precision, this profile uses most of the chrominance channel-width. This results in minimal chromatic data loss compared to the more common ‘yuv420p’ format, but increases the encoding processing time.

class ataraxis_video_system.saver.VideoEncoders(*values)

Bases: StrEnum

Stores the supported video encoders used when saving camera frames as videos via VideoSaver instances.

H264 = 'H264'

For CPU savers this is the libx264 encoder and for GPU savers this is the h264_nvenc encoder.

H265 = 'H265'

For CPU savers this is the libx265 encoder and for GPU savers this is the hevc_nvenc encoder.

class ataraxis_video_system.saver.VideoSaver(system_id, output_file, frame_width, frame_height, frame_rate, gpu=-1, video_encoder=VideoEncoders.H265, encoder_speed_preset=EncoderSpeedPresets.SLOW, input_pixel_format=InputPixelFormats.BGR, output_pixel_format=OutputPixelFormats.YUV420, quantization_parameter=15)

Bases: object

Interfaces with an FFMPEG process to continuously save the input camera frames as an MP4 video file.

This class uses the FFMPEG library and either Nvidia GPU or CPU to continuously encode and append the input stream of camera frames to an MP4 video file stored in non-volatile memory (on disk).

Parameters:

• system_id (int) – The unique identifier code of the VideoSystem instance that uses this saver interface.

• output_file (Path) – The path to the .mp4 video file to create at runtime.

• frame_width (int) – The width of the video to be encoded, in pixels.

• frame_height (int) – The height of the video to be encoded, in pixels.

• frame_rate (float) – The frame rate of the video to be created.

• gpu (int, default: -1) – The index of the GPU to use for encoding. Setting this argument to a value of -1 (default) configures the instance to instead use the CPU for encoding. Valid GPU indices can be obtained from the ‘nvidia-smi’ terminal command.

• video_encoder (VideoEncoders | str, default: <VideoEncoders.H265: 'H265'>) – The encoder to use for generating the video file. Must be one of the valid VideoEncoders enumeration members.

• encoder_speed_preset (EncoderSpeedPresets | int, default: <EncoderSpeedPresets.SLOW: 5>) – The encoding speed preset to use for generating the video file. Must be one of the valid EncoderSpeedPresets enumeration members.

• input_pixel_format (InputPixelFormats | str, default: <InputPixelFormats.BGR: 'bgr24'>) – The pixel format used by the input frame data. This argument depends on the configuration of the camera used to acquire the frames. Must be one of the valid InputPixelFormats enumeration members.

• output_pixel_format (OutputPixelFormats | str, default: <OutputPixelFormats.YUV420: 'yuv420p'>) – The pixel format to be used by the output video file. Must be one of the valid OutputPixelFormats enumeration members.

• quantization_parameter (int, default: 15) – The integer value to use for the ‘quantization parameter’ of the encoder. This determines how much information to discard from each encoded frame. Lower values produce better video quality at the expense of longer processing time and larger file size: 0 is best, 51 is worst. Note, the default value is calibrated for the H265 encoder and is likely too low for the H264 encoder.

_gpu_encoder_preset_map

Maps EncoderSpeedPresets enumeration member values to the appropriate GPU encoder speed preset values.

_cpu_encoder_preset_map

Maps EncoderSpeedPresets enumeration member values to the appropriate CPU encoder speed preset values.

_system_id

Stores the unique identifier code of the VideoSystem instance that uses this saver interface.

_ffmpeg_command

Stores the main body of the FFMPEG command used to start the video encoding process.

_repr_body

Stores the main body of the class representation string.

_ffmpeg_process

Stores the Popen object that controls the FFMPEG’s video encoding process. This is used during camera frame encoding to continuously feed the input camera frames to the encoding process.

property is_active: bool

Returns True if the instance’s encoder process is active (running).

save_frame(frame)

Sends the input frame to be added to the video file managed by the instance’s FFMPEG encoder process.

Notes

This method expects that the input frame data matches the video dimensions and input pixel format used during VideoSaver initialization.

Parameters:

frame (ndarray[tuple[Any, ...], dtype[integer[Any]]]) – The frame’s data to be encoded into the video.

Raises:

• ConnectionError – If the method is called before starting the encoder process via the start() method.

• BrokenPipeError – If the method encounters an error when submitting the frame’s data to the FFMPEG process.

Return type:

None

start()

Creates the FFMPEG encoder process and sets up the data stream to pipe incoming camera frames to the process.

Return type:

None

stop()

Stops the FFMPEG encoder process.

Return type:

None

ataraxis_video_system.saver.check_ffmpeg_availability()

Checks whether the host system has the FFMPEG library installed and available on PATH.

The presence of the FFMPEG library is determined by calling the ‘ffmpeg -version’ command.

Return type:

bool

Returns:

True if the host system has the FFMPEG library installed and available on PATH, False otherwise.

ataraxis_video_system.saver.check_gpu_availability()

Checks whether the host system has an Nvidia GPU.

The presence of a GPU is determined by calling the ‘nvidia-smi’ command. If the command runs successfully, it indicates the host-system, has an Nvidia GPU.

Return type:

bool

Returns:

True if the host system has an Nvidia GPU, False otherwise.

MCP Server

Provides a Model Context Protocol (MCP) server for agentic interaction with the library.

This module exposes camera discovery, CTI file management, runtime requirements checking, and video session management functionality through the MCP protocol, enabling AI agents to programmatically interact with the library’s core features.

ataraxis_video_system.mcp_server.check_runtime_requirements()

Checks whether the host system meets the requirements for video encoding and camera interfaces.

Verifies that FFMPEG is installed and accessible, checks for Nvidia GPU availability for hardware-accelerated encoding, and checks whether a CTI file is configured for Harvesters camera support. Returns a status indicating whether requirements are fully met, partially met, or not met.

Return type:

str

ataraxis_video_system.mcp_server.get_cti_status()

Checks whether the library is configured with a valid GenTL Producer interface (.cti) file.

The Harvesters camera interface requires the GenTL Producer interface (.cti) file to discover and interface with GeniCam-compatible cameras. Returns the configuration status and the path to the configured CTI file if one exists.

Return type:

str

ataraxis_video_system.mcp_server.get_session_status()

Returns the current status of the video session.

Reports whether a session is active and its current state (acquiring frames, saving frames, etc.).

Return type:

str

ataraxis_video_system.mcp_server.list_cameras()

Discovers all cameras compatible with the OpenCV and Harvesters interfaces.

Returns a formatted string containing information about all discovered cameras, including their interface type, index, frame dimensions, and frame rate. For Harvesters cameras, model and serial number information is also included.

Return type:

str

ataraxis_video_system.mcp_server.run_server(transport='stdio')

Starts the MCP server with the specified transport.

Parameters:

transport (Literal['stdio', 'sse', 'streamable-http'], default: 'stdio') – The transport protocol to use. Supported values are ‘stdio’ for standard input/output communication and ‘streamable-http’ for HTTP-based communication.

Return type:

None

ataraxis_video_system.mcp_server.set_cti_file(file_path)

Configures the library to use the specified CTI file for all future runtimes involving GeniCam cameras.

The Harvesters library requires the GenTL Producer interface (.cti) file to discover and interface with compatible cameras. This tool must be called at least once before using the Harvesters interface.

Parameters:

file_path (str) – The absolute path to the CTI file that provides the GenTL Producer interface. It is recommended to use the file supplied by the camera vendor, but a general Producer such as mvImpactAcquire is also acceptable.

Return type:

str

ataraxis_video_system.mcp_server.start_frame_saving()

Starts saving captured frames to the video file.

Begins writing acquired frames to an MP4 video file in the output directory. A video session must be active.

Return type:

str

ataraxis_video_system.mcp_server.start_video_session(output_directory, interface='opencv', camera_index=0, width=600, height=400, frame_rate=30, gpu_index=-1, display_frame_rate=25, *, monochrome=False)

Starts a video capture session with the specified parameters.

Creates a VideoSystem instance and begins acquiring frames from the camera. Frames are not saved until start_frame_saving is called. Only one session can be active at a time.

Important

The AI agent calling this tool MUST ask the user to provide the output_directory path before calling this tool. Do not assume or guess the output directory - always prompt the user for an explicit path.

Parameters:

• output_directory (str) – The path to the directory where video files will be saved. This must be provided by the user - the AI agent should always ask for this value explicitly.

• interface (str, default: 'opencv') – The camera interface to use (‘opencv’, ‘harvesters’, or ‘mock’). Defaults to ‘opencv’.

• camera_index (int, default: 0) – The index of the camera to use. Defaults to 0.

• width (int, default: 600) – The width of frames to capture in pixels. Defaults to 600.

• height (int, default: 400) – The height of frames to capture in pixels. Defaults to 400.

• frame_rate (int, default: 30) – The target frame rate in frames per second. Defaults to 30.

• monochrome (bool, default: False) – Determines whether to capture in grayscale. Defaults to False (color).

• gpu_index (int, default: -1) – The GPU index for hardware encoding, or -1 for CPU encoding. Defaults to -1.

• display_frame_rate (int | None, default: 25) – The rate at which to display acquired frames in a preview window. Defaults to 25 fps. Set to None to disable frame display. The display rate cannot exceed the acquisition frame rate. Note that frame display is not supported on macOS.

Return type:

str

ataraxis_video_system.mcp_server.stop_frame_saving()

Stops saving frames to the video file.

Stops writing frames to the video file while keeping the session active. Frame acquisition continues.

Return type:

str

ataraxis_video_system.mcp_server.stop_video_session()

Stops the active video capture session and releases all resources.

Stops the VideoSystem and DataLogger, freeing the camera and saving any remaining buffered frames.

Return type:

str

Command Line Interfaces (CLIs)

axvs

Serves as the entry-point for interfacing with all interactive components of the ataraxis-video-system (AXVS) library.

Usage

axvs [OPTIONS] COMMAND [ARGS]...

check

Checks whether the host system meets the requirements for CPU and (optionally) GPU video encoding.

This command allows checking whether the local system is set up correctly to support saving acquired camera frames as videos. As a minimum, this requires that the system has the FFMPEG library installed and available on the system’s Path. Additionally, to support GPU (hardware) encoding, the system must have an Nvidia GPU. Note; the presence of the GPU is evaluated by calling the ‘nvidia-smi’ command, so it must also be installed on the local system alongside the GPU for the check to work as expected.

Usage

axvs check [OPTIONS]

cti

Configures the library to use the input CTI file for all future runtimes involving GeniCam cameras.

This library relies on the Harvesters library to interface with GeniCam-compatible cameras. In turn, the Harvesters library requires the GenTL Producer interface (.cti) file to discover and interface with compatible cameras. This command must be called at least once before calling all other CLIs and APIs that rely on the Harvesters library.

Usage

axvs cti [OPTIONS]

Options

-f, --file-path <file_path>

The path to the CTI file that provides the GenTL Producer interface. It is recommended to use the file supplied by the camera vendor, but a general Producer, such as mvImpactAcquire, is also acceptable. See https://github.com/genicam/harvesters/blob/master/docs/INSTALL.rst for more details.

cti-check

Checks whether the library is configured with a valid GenTL Producer interface (.cti) file.

This command verifies if a .cti file has been configured and whether it is still valid. The Harvesters camera interface requires the GenTL Producer interface (.cti) file to discover and interface with GeniCam-compatible cameras. Use this command to verify the configuration status before attempting to use the Harvesters interface.

Usage

axvs cti-check [OPTIONS]

id

Discovers all cameras compatible with the Opencv and Harvesters interfaces and prints their identification information.

This command is primarily intended to be used during the initial system configuration to determine the positional indices of each camera in the list of all cameras discoverable by each supported interface. The discovered indices can then be used to initialize the VideoSystem instances to interface with the discovered cameras.

Usage

axvs id [OPTIONS]

mcp

Starts the Model Context Protocol (MCP) server for agentic interaction with the library.

The MCP server exposes camera discovery and CTI file management functionality through the MCP protocol, enabling AI agents to programmatically interact with the library.

Usage

axvs mcp [OPTIONS]

Options

-t, --transport <transport>

The transport protocol to use for MCP communication. Use ‘stdio’ for standard input/output communication (default, recommended for Claude Desktop integration) or ‘streamable-http’ for HTTP-based communication.

Default:

'stdio'

Options:

stdio | streamable-http

run

Creates a VideoSystem instance using the input parameters and starts an interactive imaging session.

This command allows testing various components of the VideoSystem by running an interactive session controlled via the terminal. Primarily, this CLI is designed to help with the initial identification and calibration of VideoSystem instances and does not support the full range of features offered through the VideoSystem class API.

Usage

axvs run [OPTIONS]

Options

-i, --interface <interface>

The camera interface to use for interacting with the camera hardware. It is recommended to use the ‘harvesters’ interface for all GeniCam-compatible cameras and the ‘opencv’ interface for all other cameras.

Default:

'mock'

Options:

mock | harvesters | opencv

-c, --camera-index <camera_index>

The index of the target camera in the list of all cameras discoverable through the chosen interface. This option allows selecting the desired camera if multiple are available on the host-system.

Default:

0

-g, --gpu-index <gpu_index>

The index of the GPU device to use for video encoding. Setting this option to a value below zero (default) forces the VideoSystem to use the CPU for encoding the videos. Note; GPU encoding currently requires an Nvidia GPU that supports hardware video encoding.

Default:

-1

-o, --output-directory <output_directory>

Required The path to the output directory where to save the acquired camera frames as an .mp4 video file.

-m, --monochrome

Determines whether the camera records frames in monochrome (grayscale) or colored spectrum.

Default:

False

-w, --width <width>

The width of the camera frames to acquire, in pixels.

Default:

600

-h, --height <height>

The height of the camera frames to acquire, in pixels.

Default:

400

-f, --frame-rate <frame_rate>

The rate at which to acquire the frames, in frames per second.

Default:

30