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.

ataraxis_video_system.video.video_system.MAXIMUM_QUANTIZATION_VALUE: int = 51

The maximum quantization parameter value accepted by FFMPEG encoders.

class ataraxis_video_system.video.video_system.VideoSystem(system_id, data_logger, name, 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.

  • name (str) – A colloquial human-readable name for this camera source (e.g., ‘face_camera’). Written to the camera manifest file alongside the system_id to identify the camera this VideoSystem instance controls.

  • 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 disables 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) – 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 display is not supported on macOS and is automatically disabled there.

  • 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) – Determines 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. Setting this to -1 defers the choice to the encoder’s default. 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.

_display_frame_rate

Stores the frame display rate as frames per second or 0 when display is disabled.

_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.

Camera

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

These interfaces abstract the necessary procedures to connect to the camera and continuously grab the acquired frames.

class ataraxis_video_system.video.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

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

serial_number: str | None

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

class ataraxis_video_system.video.camera.CameraInterfaces(*values)

Bases: StrEnum

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

HARVESTERS = 'harvesters'

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

MOCK = 'mock'

The mock backend used exclusively for internal library testing.

OPENCV = 'opencv'

The backend for all cameras that do not support the GenICam standard, based on the ‘OpenCV’ library and primarily compatible with consumer-grade cameras that use the USB interface.

class ataraxis_video_system.video.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. The VideoSystem constructor creates all camera interface instances based on the selected camera_interface.

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.

_model

Stores the model name of the connected camera. Populated during connect(), reset during disconnect().

_serial_number

Stores the serial number of the connected camera. Populated during connect(), reset during disconnect().

apply_configuration(config, *, strict_identity=False, blacklisted_nodes=frozenset({'CustomerIDKey', 'CustomerValueKey', 'TestPattern'}))

Applies a GenicamConfiguration to the connected camera.

Parameters:

  • config (GenicamConfiguration) – The configuration instance containing ReadWrite nodes to apply.

  • strict_identity (bool, default: False) – Determines whether to abort on camera identity mismatch instead of warning.

  • blacklisted_nodes (frozenset[str], default: frozenset({'TestPattern', 'CustomerIDKey', 'CustomerValueKey'})) – A set of node names to silently skip during validation and write operations. Defaults to DEFAULT_BLACKLISTED_NODES, which excludes vendor-specific nodes known to report ReadWrite access but reject writes at the hardware level. Pass an empty frozenset to disable blacklisting.

Raises:

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

  • ValueError – If the camera identity mismatches (strict mode) or any node is missing or not writable.

  • RuntimeError – If any non-blacklisted node write operation fails.

Return type:

None

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.

get_configuration(blacklisted_nodes=frozenset({'CustomerIDKey', 'CustomerValueKey', 'TestPattern'}))

Enumerates all ReadWrite GenICam nodes on the connected camera and returns the configuration.

Parameters:

blacklisted_nodes (frozenset[str], default: frozenset({'TestPattern', 'CustomerIDKey', 'CustomerValueKey'})) – A set of node names to exclude from the configuration. Defaults to DEFAULT_BLACKLISTED_NODES, which excludes vendor-specific nodes known to report ReadWrite access but reject writes at the hardware level. Pass an empty frozenset to disable blacklisting.

Return type:

GenicamConfiguration

Returns:

A GenicamConfiguration instance containing the camera identity and all ReadWrite node values.

Raises:

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

get_node_description(name)

Reads a single readable value node from the connected camera and returns a formatted description string.

Parameters:

name (str) – The feature name of the node to read (e.g., “Width”, “ExposureTime”).

Return type:

str

Returns:

A multi-line formatted string containing the node’s full metadata.

Raises:

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

  • ValueError – If the node is not a readable value node.

  • AttributeError – If the named node does not exist on the camera’s node map.

get_node_info(name)

Reads a single readable value node from the connected camera and returns its name and current value.

Parameters:

name (str) – The feature name of the node to read (e.g., “Width”, “ExposureTime”).

Return type:

GenicamNodeInfo

Returns:

A GenicamNodeInfo instance containing the node’s name and current value.

Raises:

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

  • ValueError – If the node is not a readable value node.

  • AttributeError – If the named node does not exist on the camera’s node map.

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:

GenericAlias[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 model: str

Returns the model name of the connected camera, or an empty string if not connected.

property node_map: NodeMap

Returns the GenICam node map of the connected camera, or raises ConnectionError if not connected.

property pixel_color_format: InputPixelFormats

Returns the pixel color format of the acquired frames.

property serial_number: str

Returns the serial number of the connected camera, or an empty string if not connected.

set_node_value(name, value)

Sets the value of a single writable (ReadWrite) GenICam feature node on the connected camera.

Parameters:

  • name (str) – The feature name of a writable node (e.g., “Width”, “ExposureTime”).

  • value (str) – The string representation of the value to write. Coerced to the node’s native type automatically.

Raises:

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

  • ValueError – If the named node does not have ReadWrite access or the value cannot be coerced.

  • RuntimeError – If the write operation fails.

Return type:

None

class ataraxis_video_system.video.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. The VideoSystem constructor creates all camera interface instances based on the selected camera_interface.

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 BGR (colored) 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[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:

GenericAlias[uint8]

Returns:

A NumPy array that stores the frame data. Colored frames have the shape (height, width, 3) using the BGR channel order, while monochrome frames retain a singleton channel dimension with the shape (height, width, 1).

Raises:

ConnectionError – 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.video.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. The VideoSystem constructor creates all camera interface instances based on the selected camera_interface.

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:

GenericAlias[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.video.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.video.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.video.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 set’ 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.

Abstracts the configuration and flow control steps typically involved in saving acquired camera frames as video files in real time.

class ataraxis_video_system.video.saver.EncoderSpeedPresets(*values)

Bases: IntEnum

Defines 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.

property cpu_preset: str

Returns the corresponding CPU encoder preset string.

property gpu_preset: str

Returns the corresponding NVIDIA GPU encoder preset string.

class ataraxis_video_system.video.saver.InputPixelFormats(*values)

Bases: StrEnum

Defines 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.video.saver.OutputPixelFormats(*values)

Bases: StrEnum

Defines 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.video.saver.VideoEncoders(*values)

Bases: StrEnum

Defines 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.video.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.

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.

_system_id

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

_ffmpeg_command

Stores the FFMPEG command arguments 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 video encoding process. This is used during camera frame encoding to continuously feed the input camera frames to the encoding process.

_stderr_output

Stores the captured stderr output from the FFMPEG process.

_stderr_thread

Stores the daemon thread that drains the FFMPEG process stderr pipe to prevent buffer saturation.

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

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

Parameters:

frame (GenericAlias[integer[Any]]) – The frame’s data to be encoded into the video.

Raises:

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

  • RuntimeError – If the FFMPEG process has terminated unexpectedly during encoding.

  • BrokenPipeError – If an error occurs 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.video.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.video.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.

GenICam Configuration

Provides data classes and helper functions for reading, writing, and managing GenICam camera configurations.

These utilities allow enumerating, inspecting, and modifying individual GenICam feature nodes, as well as dumping and loading full camera configurations to and from YAML files.

ataraxis_video_system.video.configuration.DEFAULT_BLACKLISTED_NODES: frozenset[str] = frozenset({'CustomerIDKey', 'CustomerValueKey', 'TestPattern'})

Node names silently skipped during configuration enumeration and apply operations.

Some vendor-specific nodes report ReadWrite access but reject writes at the hardware level, causing spurious errors. These nodes are excluded by default from all configuration operations. End users can override this set via the blacklisted_nodes parameter on enumerate_genicam_nodes and apply_genicam_configuration.

class ataraxis_video_system.video.configuration.GenicamConfiguration(camera_model='', camera_serial_number='', nodes=<factory>)

Bases: YamlConfig

Stores a complete GenICam camera configuration with camera identity metadata.

camera_model: str = ''

The model name of the camera that produced this configuration.

camera_serial_number: str = ''

The serial number of the camera that produced this configuration.

nodes: list[GenicamNodeInfo]

The list of ReadWrite GenICam nodes with their current values.

class ataraxis_video_system.video.configuration.GenicamNodeInfo(name, value)

Bases: object

Stores the name and value of a single GenICam feature node.

name: str

The feature name of the node (e.g., “Width”, “ExposureTime”).

value: int | float | str | bool

The current value of the node.

ataraxis_video_system.video.configuration.apply_genicam_configuration(node_map, config, current_model, current_serial, *, strict=False, blacklisted_nodes=frozenset({'CustomerIDKey', 'CustomerValueKey', 'TestPattern'}))

Applies the ReadWrite nodes from a GenicamConfiguration to the connected camera’s node map.

First validates that the camera identity matches and that all non-blacklisted nodes in the configuration exist on the device and are writable. Then applies nodes in SFNC-compliant phase order to satisfy interdependent constraints (e.g., Width/OffsetX, GainAuto/Gain, binning/dimensions).

Notes

GenICam SFNC defines dynamic constraints between nodes: OffsetX.Max = SensorWidth - Width, auto-controls lock their manual counterparts, and binning changes WidthMax/HeightMax. This function applies nodes in a fixed phase order defined by _APPLY_PHASE_ORDER to satisfy all known dependency chains. Phases 1-2 write reset values (offsets to 0, auto-controls to Off) to unlock dependent nodes and maximize dimension ranges. Phases 3-7 write target values in dependency order. Remaining nodes not covered by any phase are written last.

Parameters:

  • node_map (NodeMap) – The GenICam node map object.

  • config (GenicamConfiguration) – The configuration instance containing ReadWrite nodes to apply.

  • current_model (str) – The model name of the currently connected camera.

  • current_serial (str) – The serial number of the currently connected camera.

  • strict (bool, default: False) – Determines whether to abort on camera identity mismatch instead of warning.

  • blacklisted_nodes (frozenset[str], default: frozenset({'TestPattern', 'CustomerIDKey', 'CustomerValueKey'})) – A set of node names to silently skip during validation and write operations. Defaults to DEFAULT_BLACKLISTED_NODES, which contains vendor-specific nodes known to report ReadWrite access but reject writes at the hardware level.

Raises:

  • ValueError – If strict is True and a camera identity mismatch is detected, or if any non-blacklisted node in the configuration is missing or not writable on the target device.

  • RuntimeError – If any non-blacklisted node write operation fails.

Return type:

None

ataraxis_video_system.video.configuration.enumerate_genicam_nodes(node_map, blacklisted_nodes=frozenset({'CustomerIDKey', 'CustomerValueKey', 'TestPattern'}))

Collects the names of all writable leaf value nodes by walking the GenICam category tree from the root.

Notes

Uses an iterative stack-based traversal starting from node_map.Root. Collects ReadWrite nodes of type Integer, Float, Enumeration, Boolean, and String, skipping all other nodes. All node accesses are wrapped in try/except to gracefully handle locked or unavailable nodes. Nodes whose names appear in blacklisted_nodes are silently excluded.

Parameters:

  • node_map (NodeMap) – The GenICam node map object.

  • blacklisted_nodes (frozenset[str], default: frozenset({'TestPattern', 'CustomerIDKey', 'CustomerValueKey'})) – A set of node names to exclude from enumeration. Defaults to DEFAULT_BLACKLISTED_NODES, which contains vendor-specific nodes known to report ReadWrite access but reject writes at the hardware level.

Return type:

list[str]

Returns:

A sorted list of unique feature node names for all discovered writable leaf value nodes.

ataraxis_video_system.video.configuration.format_genicam_node(node_map, name)

Reads a single readable GenICam feature node and returns a formatted string with its full metadata.

Parameters:

  • node_map (NodeMap) – The GenICam node map object.

  • name (str) – The feature name of the node to read (e.g., “Width”, “ExposureTime”).

Return type:

str

Returns:

A multi-line formatted string containing the node’s name, type, value, access mode, description, numeric range, step increment (for Integer nodes), enumeration entries, and measurement unit (when defined).

Raises:

  • AttributeError – If the named node does not exist on the node map.

  • ValueError – If the node is not readable (must be ReadWrite or ReadOnly).

ataraxis_video_system.video.configuration.read_genicam_node(node_map, name)

Reads a single readable value node from the GenICam node map and returns its name and current value.

Parameters:

  • node_map (NodeMap) – The GenICam node map object.

  • name (str) – The feature name of the node to read (e.g., “Width”, “ExposureTime”).

Return type:

GenicamNodeInfo

Returns:

A GenicamNodeInfo instance containing the node’s name and current value.

Raises:

  • AttributeError – If the named node does not exist on the node map.

  • ValueError – If the node is not a readable value node.

ataraxis_video_system.video.configuration.write_genicam_node(node_map, name, value)

Sets the value of a single writable (ReadWrite) GenICam feature node.

Accepts a string value and coerces it to the appropriate Python type (int, float, bool, or str) based on the node’s principal_interface_type before writing.

Parameters:

  • node_map (NodeMap) – The GenICam node map object.

  • name (str) – The feature name of a writable node (e.g., “Width”, “ExposureTime”). The target node must have ReadWrite access mode.

  • value (str) – The string representation of the value to write. Coerced to the node’s native type automatically.

Raises:

  • ValueError – If the named node does not have ReadWrite access or the value cannot be coerced.

  • RuntimeError – If the write operation fails.

Return type:

None

Camera Manifest

Provides data classes and a helper function for managing camera log manifest files.

Camera log manifests identify DataLogger archives produced by ataraxis-video-system and associate each source ID with a human-readable name. The manifest file lives alongside the log archives in the DataLogger output directory.

ataraxis_video_system.video.manifest.CAMERA_MANIFEST_FILENAME: str = 'camera_manifest.yaml'

The filename used for camera log manifest files within DataLogger output directories.

class ataraxis_video_system.video.manifest.CameraManifest(sources=<factory>)

Bases: YamlConfig

Stores camera source identification data for all VideoSystem instances sharing a DataLogger.

Each entry in the sources list corresponds to one VideoSystem instance that logs frame timestamps to the same DataLogger output directory. The manifest file enables downstream tools to identify which log archives were produced by ataraxis-video-system and to associate source IDs with human-readable names.

sources: list[CameraSourceData]

The list of camera source entries registered in this manifest.

class ataraxis_video_system.video.manifest.CameraSourceData(id=0, name='')

Bases: object

Stores the identification data for a single camera source registered in a log manifest.

id: int

The source_id used by the VideoSystem instance when logging to the DataLogger.

name: str

A colloquial human-readable name for the camera source (e.g., ‘face_camera’).

ataraxis_video_system.video.manifest.write_camera_manifest(log_directory, source_id, name)

Writes or updates the camera manifest file in the specified log directory.

If the manifest file already exists (another VideoSystem instance has already registered), reads the existing manifest, appends the new source entry, and writes it back. Otherwise, creates a new manifest with a single entry.

Parameters:

  • log_directory (Path) – The path to the DataLogger output directory where the manifest file is stored.

  • source_id (int) – The source_id of the VideoSystem instance to register.

  • name (str) – The colloquial human-readable name for the camera source.

Return type:

None

Log Processing

Provides the log data processing pipeline for extracting frame timestamps from VideoSystem log archives.

ataraxis_video_system.video.log_processing.CAMERA_TIMESTAMPS_DIRECTORY: str = 'camera_timestamps'

Name of the subdirectory created under the output path for camera timestamp processing results. All tracker files and processed feather outputs are written into this subdirectory.

ataraxis_video_system.video.log_processing.LOG_ARCHIVE_SUFFIX: str = '_log.npz'

Naming convention suffix for log archives produced by assemble_log_archives().

ataraxis_video_system.video.log_processing.PARALLEL_PROCESSING_THRESHOLD: int = 2000

The minimum number of messages in a log archive required to enable parallel processing. Archives with fewer messages are processed sequentially to avoid multiprocessing overhead. Matches the threshold used internally by LogArchiveReader (2000).

ataraxis_video_system.video.log_processing.TIMESTAMP_JOB_NAME: str = 'camera_timestamp_extraction'

The job name used by the processing pipeline for camera timestamp extraction.

ataraxis_video_system.video.log_processing.TRACKER_FILENAME: str = 'camera_processing_tracker.yaml'

Filename for the processing tracker file placed in the output directory.

ataraxis_video_system.video.log_processing.execute_job(log_path, output_directory, source_id, job_id, workers, tracker, *, display_progress=True, executor=None)

Executes a single timestamp extraction job for the target log archive.

Extracts camera frame acquisition timestamps from the log archive, converts them to a Polars DataFrame, and writes the result as an IPC (Feather) file.

Parameters:

  • log_path (Path) – The path to the .npz log archive to process.

  • output_directory (Path) – The path to the directory where the output Feather file is written.

  • source_id (str) – The source ID string identifying the log archive.

  • job_id (str) – The unique hexadecimal identifier for this processing job.

  • workers (int) – The number of worker processes to use for parallel processing.

  • tracker (ProcessingTracker) – The ProcessingTracker instance used to track the pipeline’s runtime status.

  • display_progress (bool, default: True) – Determines whether to display a progress bar during timestamp extraction.

  • executor (ProcessPoolExecutor | None, default: None) – When provided, parallel processing reuses this pool instead of creating a new one. The pool is passed through to extract_logged_camera_timestamps to avoid spawning a redundant process pool.

Return type:

None

ataraxis_video_system.video.log_processing.extract_logged_camera_timestamps(log_path, n_workers=-1, *, display_progress=True, executor=None)

Extracts the video camera frame acquisition timestamps from the target .npz log file.

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 array of frame timestamps. The order of timestamps in the array 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.

Returns a contiguous numpy array instead of a Python tuple to minimize memory footprint. For a 120 fps camera recording over 1.5 hours (~648,000 frames), this reduces timestamp storage from ~25 MB (Python objects) to ~5 MB (contiguous uint64 buffer).

When an external executor is provided, batch processing is submitted to that executor instead of creating a new ProcessPoolExecutor. The caller is responsible for executor lifecycle management. This allows multiple archives with similar sizes to share a single process pool, avoiding the overhead of repeatedly spawning and tearing down worker processes.

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.

  • display_progress (bool, default: True) – Determines whether to display a progress bar during parallel batch processing.

  • executor (ProcessPoolExecutor | None, default: None) – When provided, parallel batch work is submitted to this pool instead of a newly created one, and the caller owns the pool’s lifecycle. Its worker count must match the n_workers value used for batch generation.

Return type:

GenericAlias[uint64]

Returns:

A contiguous numpy array of frame acquisition timestamps. Each timestamp is stored as the number of microseconds elapsed since the UTC epoch onset.

Raises:

ValueError – If the target path does not exist, does not have a .npz suffix, or does not point to a file.

ataraxis_video_system.video.log_processing.find_log_archive(log_directory, source_id)

Searches for a single log archive matching the target source ID under the log directory.

Recursively searches the log_directory and all subdirectories for an archive file matching the {source_id}_log.npz naming convention. Expects exactly one match per source ID within the directory tree.

Parameters:

  • log_directory (Path) – The path to the root directory to search. The directory is searched recursively, so archives may be nested at any depth below this path.

  • source_id (str) – The source ID string to match. Corresponds to the filename prefix before the _log.npz suffix.

Return type:

Path

Returns:

The path to the discovered log archive.

Raises:

  • FileNotFoundError – If the log_directory does not exist, is not a directory, or no archive matching the source ID is found.

  • ValueError – If multiple archives matching the source ID are found under the log directory.

ataraxis_video_system.video.log_processing.generate_job_ids(source_ids)

Generates unique processing job identifiers for each source ID.

Parameters:

source_ids (list[str]) – The list of source ID strings for which to generate job IDs.

Return type:

dict[str, str]

Returns:

A dictionary mapping source IDs to their generated hexadecimal job identifiers.

ataraxis_video_system.video.log_processing.prepare_tracker(tracker, jobs, universe)

Aligns the processing tracker’s job registry with the jobs requested for the current pipeline invocation.

Notes

Foreign entries are detected by comparing the tracker’s existing job IDs against the manifest-derived universe of all possible jobs for the current camera manifest, not against the invocation’s requested subset. This lets a subset invocation or a single concurrent remote job align the tracker without wiping previously-completed state for sibling jobs. Any existing entries that are not part of the universe are treated as architectural drift (the manifest itself has changed since the tracker was last written) and surfaced through a warning before the tracker is rebuilt.

The tracker is initialized when absent, reset and rebuilt (after a warning) when it contains foreign entries, and additively extended via initialize_jobs when it is missing only some requested jobs. A fully-aligned tracker is left untouched to avoid duplicate-entry warnings.

Parameters:

  • tracker (ProcessingTracker) – The ProcessingTracker instance bound to the camera_timestamps output directory.

  • jobs (list[tuple[str, str]]) – The list of (job_name, specifier) tuples the current pipeline invocation intends to execute.

  • universe (list[tuple[str, str]]) – The list of (job_name, specifier) tuples enumerating every job the manifest could produce. Used exclusively for foreign-entry detection.

Return type:

None

ataraxis_video_system.video.log_processing.resolve_recording_roots(paths)

Resolves a set of discovered log directories to their recording root directories.

Recording roots are the meaningful top-level directories that uniquely identify each recording session. Log archives and pipeline outputs may be nested at arbitrary depths below the root, but the root itself is essential for proper recording identification and display labels. Uses _extract_unique_components to identify the first path component (from the end) that uniquely distinguishes each path, then truncates each path at that component to strip shared structural subdirectories without assuming a fixed directory hierarchy.

Parameters:

paths (list[Path] | tuple[Path, ...]) – The directories containing discovered log archives. Each path is resolved to its recording root by walking up to the ancestor matching its unique component.

Return type:

tuple[Path, ...]

Returns:

A deduplicated tuple of recording root paths, one per unique recording.

Raises:

RuntimeError – If one or more paths do not contain unique components.

ataraxis_video_system.video.log_processing.run_log_processing_pipeline(log_directory, output_directory, job_id=None, log_ids=None, *, workers=-1, display_progress=True)

Processes the requested VideoSystem log archives from a single DataLogger output directory.

Supports both local and remote processing modes. In local mode (job_id is None), resolves each requested log archive by source ID, aligns a processing tracker in the output directory with the requested jobs, and executes them sequentially. In remote mode (job_id is provided), aligns the tracker with the full job universe derived from the camera manifest, then resolves and executes only the single archive matching the requested job ID. The universe alignment lets independent remote jobs share one tracker without resetting each other’s state, which supports running every source in parallel under an external scheduler.

In local mode, all resolved archives must reside in the same directory. If the log_directory contains archives from multiple DataLogger instances (in separate subdirectories), each must be processed independently. Use the MCP batch processing tools to orchestrate multi-directory workflows.

Parameters:

  • log_directory (Path) – The path to the root directory to search for .npz log archives. The directory is searched recursively, so archives may be nested at any depth below this path.

  • output_directory (Path) – The path to the root output directory. A camera_timestamps/ subdirectory is created automatically under this path, and all tracker and feather output files are written there.

  • job_id (str | None, default: None) – The unique hexadecimal identifier for the processing job to execute. If provided, only the job matching this ID is executed (remote mode). If not provided, all requested jobs are run sequentially with automatic tracker management (local mode).

  • log_ids (list[str] | None, default: None) – A list of source log IDs to process in local mode. Each ID must correspond to exactly one archive under the log directory, and all archives must reside in the same parent directory. If not provided, reads the camera_manifest.yaml file from the log directory to resolve all registered source IDs. This argument is ignored in remote mode, where the executed job is selected solely by job_id.

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

  • display_progress (bool, default: True) – Determines whether to display progress bars during timestamp extraction. Defaults to True for interactive CLI use. Set to False for MCP batch processing.

Raises:

  • FileNotFoundError – If the log_directory does not exist, a requested log ID has no matching archive, or no camera manifest is found.

  • ValueError – If the provided job_id does not match any job in the manifest universe, if no source IDs can be resolved, if a requested log ID matches multiple archives, or if resolved archives span multiple directories.

Return type:

None

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

Allows discovering compatible camera devices and verifying host-system compatibility.

Usage

axvs check [OPTIONS] COMMAND [ARGS]...

compatibility

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 compatibility [OPTIONS]

devices

Discovers all cameras compatible with the library 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 check devices [OPTIONS]

configure

Allows working with the configuration of the GenTL- (Harvesters)-compatible cameras.

Usage

axvs configure [OPTIONS] COMMAND [ARGS]...

Options

-b, --blacklisted-node <blacklisted_node>

GenICam node name to exclude from configuration operations. Repeat to specify multiple nodes. Some vendor-specific nodes report ReadWrite access but reject writes at the hardware level. Modify this list to match your camera hardware. Use –no-blacklist to disable all blacklisting.

Default:

'CustomerIDKey', 'CustomerValueKey', 'TestPattern'

--no-blacklist

Disables all node blacklisting. When set, all ReadWrite nodes are included in configuration operations regardless of the –blacklisted-node values.

dump

Dumps the full GenICam configuration of a connected Harvesters camera to a YAML file.

The output YAML includes all writable (ReadWrite) nodes with their current values, as well as the camera model and serial number for identity validation.

Usage

axvs configure dump [OPTIONS]

Options

-c, --camera-index <camera_index>

The index of the Harvesters camera to dump the configuration from.

Default:

0

-o, --output-file <output_file>

Required The path to the output YAML file to write the configuration to.

load

Loads a GenICam configuration from a YAML file onto a connected Harvesters camera.

Applies all writable nodes from the configuration file to the camera. Optionally validates that the camera model and serial number match the configuration file.

Usage

axvs configure load [OPTIONS]

Options

-c, --camera-index <camera_index>

The index of the Harvesters camera to load the configuration onto.

Default:

0

-f, --config-file <config_file>

Required The path to the YAML configuration file to load.

--strict

If set, aborts the operation when a camera identity mismatch is detected between the configuration file and the connected camera.

Default:

False

read

Reads GenICam node information from a connected Harvesters camera.

If a node name is provided, displays detailed information about that specific node. Otherwise, lists all writable (ReadWrite) nodes with their current values.

Usage

axvs configure read [OPTIONS]

Options

-c, --camera-index <camera_index>

The index of the Harvesters camera to read the configuration from.

Default:

0

-n, --node-name <node_name>

The name of a specific GenICam node to read. If omitted, lists all writable (ReadWrite) nodes.

write

Writes a value to a GenICam node on a connected Harvesters camera.

The string value is automatically converted to the appropriate type (integer, float, boolean, or string) based on the node’s type.

Usage

axvs configure write [OPTIONS]

Options

-c, --camera-index <camera_index>

The index of the Harvesters camera to write the configuration to.

Default:

0

-n, --node-name <node_name>

Required The name of the GenICam node to write.

-v, --value <value>

Required The value to write to the node. The value is automatically converted to the type expected by the node.

cti

Allows working with the GenTL Producer interface (.cti) files.

Usage

axvs cti [OPTIONS] COMMAND [ARGS]...

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]

set

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 set [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.

mcp

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

The MCP server exposes camera discovery, CTI file management, video session control, GenICam configuration, camera manifest management, and log processing 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

process

Processes VideoSystem log archives to extract frame timestamps.

Functions as the entry point for processing the data stored in the .npz log archives generated by VideoSystem instances during runtime. Each specified log ID must correspond to exactly one archive under the log directory.

Usage

axvs process [OPTIONS]

Options

-ld, --log-directory <log_directory>

Required The path to the root directory to search for .npz log archives. Searched recursively.

-od, --output-directory <output_directory>

Required The path to the directory where processed output files are written. Created automatically if it does not exist.

-id, --job-id <job_id>

The unique hexadecimal identifier for this processing job. If provided, runs only the matching job (remote mode).

-li, --log-id <log_id>

Source log ID to process. Repeat to specify multiple IDs. If not provided, resolves all source IDs from the camera_manifest.yaml file in the log directory.

-w, --workers <workers>

The number of worker processes to use. Set to a value below 1 (default -1) to use all available CPU cores.

Default:

-1

-p, --progress, --no-progress

Determines whether to display progress bars during timestamp extraction.

Default:

True

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