Video

Provides the core library assets for camera acquisition, video encoding, GenICam configuration, camera manifest management, and frame-acquisition timestamp log processing.

class ataraxis_video_system.video.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, or 0 for Harvesters cameras that do not implement the optional AcquisitionFrameRate feature.

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.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 that simulates frame acquisition without camera hardware, used for testing and dry runs.

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

sources: list[CameraSourceData]

The list of camera source entries registered in this manifest.

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

class ataraxis_video_system.video.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.ExtractedDataColumns(*values)

Bases: StrEnum

Defines the columns the extracted camera timestamp table carries, in the order it stores them.

FRAME_TIME = 'frame_time_us'

The frame acquisition timestamps, in microseconds elapsed since the UTC epoch onset.

class ataraxis_video_system.video.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.GenicamNodeInfo(name, value, selectors=<factory>)

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”).

selectors: dict[str, str | int]

The selector node values that address the instance this entry describes, empty for an unselected node.

SFNC multiplexes some features behind a selector, so a camera holds one BalanceRatio per BalanceRatioSelector entry rather than a single value. This mapping pins the instance the value belongs to, and it is applied to the camera before the value is read or written.

value: int | float | str | bool

The current value of the node.

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

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 that 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 adopts the camera’s AcquisitionFrameRate value, or reports 0 for cameras that do not implement that optional feature.

  • frame_width (int | None, default: None) – The desired width of the acquired frames, in pixels. Note that 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({'CustomerIDKey', 'CustomerValueKey', 'TestPattern'})) – 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.

Raises:

  • NotImplementedError – If the GenICam camera runtime is not available in this environment.

  • FileNotFoundError – If no .cti file path has been configured or the configured file does not exist.

  • OSError – If the configured .cti file is not a loadable GenTL Producer.

  • IndexError – If the camera index does not address one of the cameras the configured GenTL Producer discovers.

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), which is the requested rate for cameras that do not implement the optional AcquisitionFrameRate feature.

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({'CustomerIDKey', 'CustomerValueKey', 'TestPattern'})) – 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.

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

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

  • 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.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.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.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.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. Note, the default value is calibrated for the H265 encoder and is likely too low for the H264 encoder.

_started

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

_shutdown_lock

Stores the lock that serializes the teardown between the stop() method and the watchdog thread, so exactly one of the two releases the shared memory buffer.

_multiprocessing_manager

Stores the SyncManager instance used to create the multiprocessing Queue that pipes frames from the producer process to the consumer process.

_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, if the managed camera acquires frames that do not use the 8-bit unsigned integer data type, or if the managed camera acquires frames in a color format outside the unpacked Monochrome, RGB, and BGR families.

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

  • OverflowError – If ‘system_id’ falls outside the 0 to 255 range the uint8 identifier supports.

  • NotImplementedError – If the Harvesters camera interface is requested where the GenICam runtime is absent, which is every Intel Mac and every macOS host running Python 3.14.

  • FileNotFoundError – If the Harvesters camera interface is requested before a .cti file has been configured, or if the configured .cti file no longer exists.

  • OSError – If the configured .cti file is not a loadable GenTL Producer.

  • IndexError – If the ‘camera_index’ exceeds the number of cameras the configured GenTL Producer discovers.

  • BrokenPipeError – If the validation frame grab from the managed camera fails.

  • Timeout – If the camera manifest’s .lock file cannot be acquired within the timeout period.

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. If the consumer process does not save all buffered frames within the shutdown timeout, it is abandoned and any unprocessed data is discarded.

The teardown is claimed under a lock the watchdog thread takes as well, so exactly one of the two releases the shared memory buffer. The lock is released before this method joins that thread, since the watchdog acquires the same lock and holding it across the join would leave each side waiting on the other.

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

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.

Raises:

  • NotImplementedError – If the GenICam camera runtime is not available in this environment.

  • FileNotFoundError – If the supplied .cti file does not exist.

  • OSError – If the supplied .cti file is not a loadable GenTL Producer.

Return type:

None

ataraxis_video_system.video.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). The AXVS_CTI_PATH environment variable takes precedence over the persisted path, matching the resolution order applied when connecting to a camera.

Return type:

Path | None

Returns:

The Path to the configured .cti file if one exists and is valid, or None otherwise. Also returns None where the GenICam runtime that consumes the Producer is absent, which is every Intel Mac and every macOS host running Python 3.14.

ataraxis_video_system.video.check_ffmpeg_availability()

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

Return type:

bool

Returns:

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

ataraxis_video_system.video.check_gpu_availability()

Checks whether the host system has an Nvidia GPU.

Return type:

bool

Returns:

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

ataraxis_video_system.video.discover_camera_ids()

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

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.

For Harvesters cameras, this function requires a valid CTI file to be configured via the add_cti_file() function, the ‘axvs cti set’ CLI command, or the AXVS_CTI_PATH environment variable, which takes precedence over the persisted path. If no CTI file is configured, Harvesters camera discovery is skipped. Harvesters discovery is also skipped where the GenICam runtime is absent, which is every Intel Mac and every macOS host running Python 3.14.

Return type:

tuple[CameraInformation, ...]

Returns:

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

ataraxis_video_system.video.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({'CustomerIDKey', 'CustomerValueKey', 'TestPattern'})) – 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.extract_logged_camera_timestamps(log_path, workers=-1, *, display_progress=True, executor=None)

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

Reads the ‘.npz’ archive that the assemble_log_archives() function of ataraxis-data-structures builds from a VideoSystem instance’s DataLogger output 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

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.

  • workers (int, default: -1) – The number of parallel worker processes (CPU cores) to use for processing. Setting this to a value below 1 auto-resolves the count to every available CPU core minus the cores reserved for the host system. 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 workers value used for batch generation, and the caller is responsible for the worker thread limit its processes inherit.

Return type:

NDArray[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, does not point to a file, or if the archive carries no onset timestamp message.

ataraxis_video_system.video.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 a value type (Integer, Float, Boolean, String, or Enumeration), or is not readable (must be ReadWrite or ReadOnly).

ataraxis_video_system.video.genicam_runtime_available()

Determines whether the GenICam camera runtime is available in this environment.

The runtime is supplied by the ‘harvesters’ and ‘genicam’ distributions, which this library installs on every platform other than the Intel Macs and the macOS hosts running Python 3.14, where ‘genicam’ publishes no wheel.

Return type:

bool

Returns:

True when the runtime is importable, False otherwise.

ataraxis_video_system.video.harvester_connection(camera_index)

Opens a temporary connection to the target GenICam camera for the duration of the managed block.

Notes

The camera is created with a placeholder system identifier, since a connection opened this way exposes the camera’s GenICam node map rather than acquiring frames. The connection is always closed on exit, which releases the GenTL handle for other processes.

Parameters:

camera_index (int) – The index of the camera in the list of all cameras discoverable by Harvesters.

Yields:

The connected camera interface.

ataraxis_video_system.video.read_camera_configuration(camera_index, blacklisted_nodes=frozenset({'CustomerIDKey', 'CustomerValueKey', 'TestPattern'}))

Reads the live GenICam configuration of the target camera.

Notes

Opens and closes its own connection, so the GenTL handle is released before this function returns rather than held for as long as the caller holds the configuration.

Parameters:

  • camera_index (int) – The index of the camera in the list of all cameras discoverable by Harvesters.

  • blacklisted_nodes (frozenset[str], default: frozenset({'CustomerIDKey', 'CustomerValueKey', 'TestPattern'})) – 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:

The camera identity and the current value of every writable node the blacklist retains.

Raises:

  • NotImplementedError – If the GenICam camera runtime is not available in this environment.

  • FileNotFoundError – If no .cti file path has been configured or the configured file does not exist.

  • OSError – If the configured .cti file is not a loadable GenTL Producer.

  • IndexError – If the camera index does not address one of the cameras the configured GenTL Producer discovers.

ataraxis_video_system.video.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.resolve_camera_video_path(output_directory, system_id)

Resolves the path of the video file the target VideoSystem writes its acquired frames to.

Notes

The identifier is zero-padded so that a directory holding the output of several systems sorts its recordings in identifier order.

Parameters:

  • output_directory (Path) – The directory the VideoSystem writes its output into.

  • system_id (int) – The identifier of the VideoSystem whose output path is resolved.

Return type:

Path

Returns:

The path to the system’s video file.

ataraxis_video_system.video.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, replaces the entry registered under the same source_id or appends a new entry when the manifest carries none, and writes it back. Otherwise, creates a new manifest with a single entry.

Notes

The read, the replacement, and the write are performed under a lock file held beside the manifest, since the three steps do not form an atomic sequence on their own. Both the threads that concurrent MCP tool calls run on and the separate processes that each VideoSystem instance registers from reach this function, so the lock is a file lock rather than a thread lock.

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.

Raises:

  • Timeout – If the manifest’s .lock file cannot be acquired within the timeout period.

  • YAMLError – If an existing camera manifest does not hold a well-formed YAML document.

  • MissingValueError – If an existing camera manifest omits a field the CameraManifest class requires.

Return type:

None

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

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

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.

ataraxis_video_system.video.video_system.MAXIMUM_QUANTIZATION_VALUE: int = 51

The maximum quantization parameter value accepted by FFMPEG encoders.

ataraxis_video_system.video.camera.GENICAM_UNAVAILABLE_REASON: str = "The 'harvesters' and 'genicam' distributions that supply the GenICam camera runtime install together with this library on this platform, so a runtime that does not import indicates a damaged installation. Reinstall the library to restore the GenICam camera interface."

Explains why the GenICam camera runtime is unavailable, which every interface reports when the runtime is absent.

The explanation is resolved from the host rather than from the failed import, because the hosts that install no runtime report an expected limitation while every other host installs it alongside the library, making an absent runtime a broken environment there. Resolving it as a single conditional expression keeps both wordings out of a platform branch that only one host is ever able to execute.

Orchestration

Provides the orchestration layer: the job identity and output layout, the archive-derived sizing model, the manifest-derived job resolution, the single-job runner, the shared-pool batch engine, and the sequential pipeline.

class ataraxis_video_system.orchestration.ActiveJob(job, sizing, future)

Bases: object

Tracks one job executing in a worker of the shared job pool.

future: Future[None]

The future the pool returned, which carries the job body’s outcome.

job: JobDescriptor

The descriptor the pool was handed.

sizing: JobSizing

The resource figures this job was admitted at.

class ataraxis_video_system.orchestration.ArchiveFootprint(message_count, archive_bytes)

Bases: object

Describes the on-disk properties of one log archive that size the job reading it.

archive_bytes: int

The size of the archive file on disk.

message_count: int

The number of data messages the archive holds.

class ataraxis_video_system.orchestration.JobDescriptor(log_directory, archive_path, output_directory, tracker_path, job_name, job_id, source_id, core_weight)

Bases: object

Describes one camera timestamp extraction job, addressed by the single log archive it reads.

Notes

Every field is a path, a string, or an integer, so an instance pickles into a spawned worker and crosses a scheduler boundary or a tool payload unchanged.

The archive path is resolved rather than optional, so a dispatched job never searches the tree.

The figures a sizing pass produces live in the paired JobSizing record, which a worker never sees.

archive_path: Path

The path to the .npz log archive this job reads.

core_weight: int

The cores this job occupies while it runs, which is the width of the extraction pool its body opens when it holds more than one core.

property dispatch_key: tuple[str, str]

Returns the tracker path and job identifier pair that identifies this job across the batch.

classmethod for_archive(archive_path, output_directory, tracker_path, source_id, log_directory=None, core_weight=1)

Builds a descriptor for one archive an external scheduler has already resolved.

Notes

Derives the job identifier as this library’s own preparation does, so one built here addresses the same tracker entry.

Parameters:

  • archive_path (Path) – The path to the .npz log archive the job reads.

  • output_directory (Path) – The path to the directory the job writes its output file into.

  • tracker_path (Path) – The path to the ProcessingTracker file that records the job’s outcome.

  • source_id (str) – The identifier of the camera source whose archive the job reads.

  • log_directory (Path | None, default: None) – The path to the DataLogger output directory holding the archive. Leaving this unset uses the archive’s own parent directory.

  • core_weight (int, default: 1) – The cores the job occupies while it runs.

Return type:

JobDescriptor

Returns:

The built descriptor.

classmethod from_mapping(mapping)

Reconstructs a descriptor from the mapping a caller received across a tool boundary.

Parameters:

mapping (Mapping[str, Any]) – The mapping to read, carrying every field name to_mapping writes.

Return type:

JobDescriptor

Returns:

The reconstructed descriptor.

Raises:

ValueError – If a required key is absent, or if a value cannot be read as the type its field declares.

job_id: str

The unique hexadecimal identifier of this job in its tracker.

job_name: str

The tracker job name this job is registered under.

log_directory: Path

The path to the DataLogger output directory whose tree holds the log archive.

output_directory: Path

The path to the directory this job writes its output file into.

source_id: str

The identifier of the camera source whose archive this job reads.

to_mapping()

Renders this descriptor as the flat mapping the interface layer exchanges.

Notes

Every value is a string or an integer, so the mapping reconstructs through from_mapping without loss.

Return type:

dict[str, str | int]

Returns:

The descriptor’s fields keyed by their field names, with every path rendered as a string.

tracker_path: Path

The path to the ProcessingTracker file that records this job’s outcome.

class ataraxis_video_system.orchestration.JobExecutionState(all_jobs=<factory>, pending_jobs=<factory>, active_jobs=<factory>, core_budget=1, memory_budget_mb=1024, pool_size=1, lock=<factory>, wakeup=<factory>, manager_thread=None, canceled=False, finished_jobs=<factory>, pool_broken=False, broken_jobs=<factory>, pool_rebuilds=0, requeue_counts=<factory>)

Bases: object

Tracks runtime state for one batch execution session budgeted by both cores and memory.

Notes

Every job body runs in a worker of one shared pool that outlives it. A body admitted at more than one core opens its own extraction pool at that width, while a body admitted at a single core runs sequentially and opens none. Total live processes are the pool’s slot count plus the cores of every running job that holds more than one core, and both terms are budgeted.

active_jobs: dict[tuple[str, str], ActiveJob]

Jobs currently executing, keyed by dispatch key so a broken future is matched to its descriptor.

all_jobs: dict[tuple[str, str], JobDescriptor]

Every submitted job, keyed by its dispatch key.

broken_jobs: list[tuple[JobDescriptor, JobSizing]]

The jobs a pool break killed, awaiting requeue once the pool is rebuilt.

canceled: bool

Determines whether the execution session has been canceled.

core_budget: int

The cores the batch may commit across all concurrently running jobs.

finished_jobs: set[tuple[str, str]]

The dispatch keys of the jobs this session drove to a terminal outcome, whether the job body reached one or the engine recorded one for it. A tracker records every job that ever wrote to its directory, so a session reports its own outcomes by intersecting the tracker against this set. A job a pool break requeues is recorded only once it stops being retried.

lock: lock

The lock guarding every mutation of the job queues.

manager_thread: Thread | None

The background thread running the execution manager, or None before the session starts it.

memory_budget_mb: int

The memory the batch may commit across all concurrently running jobs.

pending_jobs: list[tuple[JobDescriptor, JobSizing]]

Jobs awaiting admission, each paired with the figures it was sized at.

pool_broken: bool

Determines whether the shared pool broke and awaits a rebuild.

pool_rebuilds: int

The times the shared pool has been rebuilt during this session.

pool_size: int

The job slots the shared pool opens, every one of which is warmed when the pool is created.

requeue_counts: dict[tuple[str, str], int]

The requeues charged to each job, keyed by dispatch key. Only a job that broke the pool while running alone is charged, since a break fails every in-flight job whatever caused it.

wakeup: Event

The signal that ends the manager’s wait between dispatch passes. A caller finishing a session sets it, so the manager observes the cleared queue at once rather than after the poll interval.

class ataraxis_video_system.orchestration.JobSet(log_directory, output_directory, tracker_path, universe, jobs, skipped_sources)

Bases: object

Describes the dispatchable extraction jobs one invocation prepared for one log directory.

jobs: tuple[JobDescriptor, ...]

Every dispatchable job this set holds, in ascending source identifier order.

log_directory: Path

The root directory holding the manifest and the log archives.

output_directory: Path

The subdirectory the preparation created, which holds the tracker and every output file.

skipped_sources: tuple[tuple[str, str], ...]

Each source that yielded no job, paired with the reason. Always empty under strict sourcing, where a source that cannot be prepared raises instead.

tracker_path: Path

The path to the ProcessingTracker file recording every job in this set.

universe: tuple[tuple[str, str], ...]

Every job the manifest defines, which is the set the tracker is aligned against.

class ataraxis_video_system.orchestration.JobSizing(cores, memory_mb)

Bases: object

Describes the resources one job receives, as one sizing pass resolved them.

cores: int

The CPU cores the job occupies while it runs, which is the width of the extraction pool its body opens once it holds more than one core.

memory_mb: int

The memory the job occupies at its peak, in megabytes.

class ataraxis_video_system.orchestration.JobSource(source_id, name, archive_path)

Bases: object

Describes one camera source the manifest registers and the log archive it produced.

archive_path: Path | None

The path to the source’s log archive, or None when the tree holds no single archive for it.

name: str

The colloquial name the manifest records for the source.

source_id: str

The identifier of the source, as it appears in every job specifier and every archive filename.

class ataraxis_video_system.orchestration.JobUniverse(log_directory, manifest_path, sources, universe, possible)

Bases: object

Describes every extraction job one log directory’s manifest defines and the subset its archives back.

property archives: dict[str, Path]

Returns the resolved archive of each source that has one, keyed by that source identifier.

log_directory: Path

The root directory the resolution searched.

manifest_path: Path | None

The path to the single camera manifest the directory holds, or None when the tree holds none.

possible: tuple[tuple[str, str], ...]

The subset of the universe whose archive resolved to exactly one file under the log directory.

sources: tuple[JobSource, ...]

Every source the manifest registers, in ascending source identifier order.

universe: tuple[tuple[str, str], ...]

Every job the manifest defines, as job name and source identifier pairs.

Notes

This is a manifest fingerprint rather than an invocation fingerprint, so every invocation aligns a tracker against the same set and no invocation resets the jobs it did not request.

class ataraxis_video_system.orchestration.OutputLayout(*values)

Bases: StrEnum

Defines the filesystem names an extraction job writes its tracker and its output files under.

DIRECTORY_NAME = 'camera_timestamps'

The subdirectory created under a caller’s output path for the tracker and the extracted files.

FILE_PREFIX = 'camera_'

The prefix of every output file an extraction job writes.

FILE_SUFFIX = '.feather'

The filename suffix of every output (Arrow IPC) file an extraction job writes.

TIMESTAMPS_INFIX = '_timestamps'

The infix marking an output file as holding frame acquisition timestamps.

TRACKER_FILENAME = 'camera_processing_tracker.yaml'

The processing tracker file recording the outcome of every job writing to one directory.

ataraxis_video_system.orchestration.estimate_job_memory_mb(footprint, cores)

Estimates the memory one extraction job holds at its allocated core count.

Notes

A job holding more than one core splits its archive across an extraction pool, and every child of that pool opens the archive itself. The archive’s message directory is therefore held once per core, and the body is charged one more reader’s worth for the working set it holds alongside its pool. A job holding a single core takes the sequential path, which opens no pool and holds the body’s reader alone.

Parameters:

  • footprint (ArchiveFootprint) – The footprint of the archive this job reads.

  • cores (int) – The cores this job holds, which is how many extraction pool children it opens, or none when it is one.

Return type:

int

Returns:

The memory this job holds, in megabytes, carrying the estimate tolerance and rounded up to the reporting quantum.

ataraxis_video_system.orchestration.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.

Notes

Delegates the job’s state transitions to the tracker’s run_job() context manager. The context marks the job as running, completes it when the block returns, and marks it as failed with the exception’s message before re-raising.

Writes the feather file directly into the output directory, creates no directory, and registers no job on the tracker, so a scheduler owning its own tracker and output layout dispatches this function unchanged.

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 identifier of the camera source whose archive is processed.

  • 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 tracker recording this job’s outcome.

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

Return type:

None

ataraxis_video_system.orchestration.finish_execution_session(state)

Waits for a canceled execution session’s manager thread to end.

Notes

Wakes the manager rather than waiting out its poll interval, so a caller that cleared the queue observes the end of the session as soon as it happens. The wait is bounded, and a manager inside the pool’s warm-up or its shutdown can outlast that bound, so the caller reads the returned flag to learn whether the slot is free.

Parameters:

state (JobExecutionState) – The execution state whose manager thread is awaited.

Return type:

bool

Returns:

True when the state holds no manager thread or its manager thread ended within the allotted time, and False when it is still running.

ataraxis_video_system.orchestration.generate_job_ids(source_ids)

Generates the processing job identifier of every requested camera source.

Parameters:

source_ids (Sequence[str]) – The camera source identifiers to generate job identifiers for.

Return type:

dict[str, str]

Returns:

The generated hexadecimal job identifier of each source, keyed by that source identifier.

ataraxis_video_system.orchestration.get_execution_state()

Returns the active batch log processing execution state, or None when no session exists.

Return type:

JobExecutionState | None

ataraxis_video_system.orchestration.group_jobs_by_tracker(state)

Groups every job in an execution state by the tracker file that records it.

Batches the jobs sharing a tracker so each tracker file is deserialized once when iterating over the groups.

Parameters:

state (JobExecutionState) – The active job execution state holding the job registry.

Return type:

dict[Path, list[JobDescriptor]]

Returns:

The jobs recorded by each tracker, keyed by that tracker’s path.

ataraxis_video_system.orchestration.prepare_jobs(log_directory, output_directory, source_ids=None, job_id=None, *, strict_sources=True)

Resolves and registers the camera timestamp extraction jobs of one log directory.

Notes

Materializes the output subdirectory and aligns the tracker against the manifest universe, which is every write this call performs outside a job’s own output. The prepared job list lives in the returned set rather than on disk.

Reads no archive. Every job carries the declared allocation as its width, which the sizing pass replaces with the width the job’s own archive resolves to.

The tracker is aligned against the whole manifest universe whichever subset this call prepares, so several invocations naming different jobs share one tracker without resetting each other’s recorded outcomes.

A tree holding no manifest is rejected whatever the sourcing mode, because the absent manifest is a property of the directory rather than of any one requested source.

Parameters:

  • log_directory (Path) – The root directory whose tree holds the camera manifest and the log archives.

  • output_directory (Path) – The root output directory. The library’s own subdirectory is created under it.

  • source_ids (Sequence[str] | None, default: None) – The sources to prepare jobs for, or None to prepare every source the manifest registers. The argument is ignored when a job identifier selects the work.

  • job_id (str | None, default: None) – The hexadecimal identifier of the single job to prepare. Leaving this unset prepares every requested source.

  • strict_sources (bool, default: True) – Determines whether a source that cannot be prepared stops the call. When set, a requested source the manifest does not register, or one whose archive does not resolve to exactly one file, raises. When unset, such a source is recorded in the returned set’s skipped sources with its reason.

Return type:

JobSet

Returns:

The prepared job set.

Raises:

  • FileNotFoundError – If the log directory does not exist, if the log directory’s tree holds no camera manifest, or if a requested source’s archive is absent under strict sourcing.

  • ValueError – If the tree holds more than one camera manifest, if a manifest registers no sources, if a requested source or job identifier is not registered, or if the resolved archives span several directories.

  • OSError – If any directory beneath the log directory cannot be read.

  • YAMLError – If the camera manifest does not hold a well-formed YAML document.

  • MissingValueError – If the camera manifest omits a field the CameraManifest class requires.

  • TimeoutError – If the tracker’s .lock file cannot be acquired within the timeout period.

ataraxis_video_system.orchestration.resolve_core_budget(requested_budget)

Resolves the cores a batch may commit across all of its concurrently running jobs.

Parameters:

requested_budget (int) – The cores the caller requested. A non-positive value auto-resolves to every available core minus the reserved host cores.

Return type:

int

Returns:

The cores the batch may commit, always at least one.

ataraxis_video_system.orchestration.resolve_job_workers(footprint)

Resolves the cores one extraction job receives, from the archive it reads.

Notes

The stage offers no width between the two it emits, because the speedup between one core and the declared allocation is smooth enough that a narrower pool costs a job time without returning a core the batch can place elsewhere.

Parameters:

footprint (ArchiveFootprint) – The footprint of the archive this job reads.

Return type:

int

Returns:

The cores this job receives, which is one or the declared allocation.

ataraxis_video_system.orchestration.resolve_jobs(log_directory)

Resolves the extraction job universe of one log directory and the subset its archives back.

Notes

Reads the manifest and indexes the archive filenames, decoding no message and writing nothing, so a caller enumerates a directory’s jobs without launching or materializing anything. Two tree walks serve any number of sources, one for the manifest and one indexing every archive name the manifest implies.

One recording writes one VideoSystem to one DataLogger, so a tree holding several manifests spans several recordings and is rejected rather than resolved against the first manifest found. A tree holding no manifest holds no camera jobs, and yields an empty universe rather than an error.

Parameters:

log_directory (Path) – The root directory whose tree is searched for the camera manifest and the log archives.

Return type:

JobUniverse

Returns:

The resolved job universe.

Raises:

  • FileNotFoundError – If the log directory does not exist or is not a directory.

  • ValueError – If the tree holds more than one camera manifest, or if a manifest registers no sources.

  • OSError – If any directory beneath the log directory cannot be read.

  • YAMLError – If the camera manifest does not hold a well-formed YAML document.

  • MissingValueError – If the camera manifest omits a field the CameraManifest class requires.

ataraxis_video_system.orchestration.resolve_memory_budget_mb(requested_budget_mb)

Resolves the memory a batch may commit across all of its concurrently running jobs.

Parameters:

requested_budget_mb (int) – The memory the caller requested, in megabytes. A non-positive value auto-resolves to a share of the host’s physical memory.

Return type:

int

Returns:

The memory the batch may commit, in megabytes. A positive request is returned verbatim, while an auto-resolved budget is held to at least the auto-resolution floor.

ataraxis_video_system.orchestration.resolve_pool_size(job_count, core_budget, memory_budget_mb)

Resolves the job slots one batch’s shared pool opens.

Notes

A slot holds a job rather than a core, so the count covers the widest running set admission can produce. Every slot is warmed at creation and holds a spawned child’s baseline memory for the whole session, so the count is held to the bodies half the memory budget can hold.

Parameters:

  • job_count (int) – The jobs the batch holds.

  • core_budget (int) – The cores the batch may commit across all concurrently running jobs.

  • memory_budget_mb (int) – The memory the batch may commit across all concurrently running jobs.

Return type:

int

Returns:

The job slots the shared pool opens, always at least one.

ataraxis_video_system.orchestration.resolve_timestamps_path(output_directory, source_id)

Resolves the path of the file holding the target source’s extracted timestamps.

Parameters:

  • output_directory (Path) – The directory the extraction jobs write their output into.

  • source_id (str) – The identifier of the camera source whose output path is resolved.

Return type:

Path

Returns:

The path to the source’s timestamp file.

ataraxis_video_system.orchestration.run_log_processing_pipeline(log_directory, output_directory, job_id=None, source_ids=None, *, workers=-1, display_progress=True)

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

Supports both local and external 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, and executes the jobs sequentially. In external mode (job_id is provided), resolves and executes only the single archive matching the requested job ID.

Notes

The tracker is aligned against the full job universe the camera manifest defines in both modes, which lets independent external jobs share one tracker without resetting each other’s state.

Each job runs at the width the caller named, or at the width its own archive resolves to when the caller named none. Jobs run one at a time, so this path weighs nothing against a core or a memory budget.

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 selecting external mode, or None to select local mode.

  • source_ids (Sequence[str] | None, default: None) – The camera source IDs to process in local mode. Each ID must be registered in the camera manifest and correspond to exactly one archive under the log directory. If not provided, resolves all registered source IDs from the manifest. This argument is ignored in external mode.

  • workers (int, default: -1) – The workers every job receives. A positive value is used verbatim. A non-positive value resolves the width from each archive, which is one worker below the parallel extraction threshold and the declared per-job allocation above it.

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

Raises:

  • FileNotFoundError – If the log directory does not exist, if the log directory’s tree holds no camera manifest, or if a requested source’s archive is absent.

  • ValueError – If the tree holds more than one camera manifest, if a manifest registers no sources, if a requested source or job identifier is not registered, if the resolved archives span several directories, or if a resolved log archive carries no onset timestamp message.

  • OSError – If any directory beneath the log directory cannot be read.

  • YAMLError – If the camera manifest does not hold a well-formed YAML document.

  • MissingValueError – If the camera manifest omits a field the CameraManifest class requires.

  • TimeoutError – If the tracker’s .lock file cannot be acquired within the timeout period.

Return type:

None

ataraxis_video_system.orchestration.session_is_active(state)

Determines whether an execution state is still running its manager thread.

Notes

A finished session’s state stays readable, so a status reader consults it after the batch ends.

Parameters:

state (JobExecutionState | None) – The execution state to test, or None when no session exists.

Return type:

bool

Returns:

True when the state holds a manager thread that has started and has not yet ended.

ataraxis_video_system.orchestration.size_archive_job(archive_path)

Resolves the cores and the memory one extraction job receives, from the archive it reads.

Notes

Reads the archive once and answers both halves of the sizing model from that read, so a scheduler planning this stage reproduces neither the width rule nor the memory model.

Parameters:

archive_path (Path) – The path to the .npz log archive the job reads.

Return type:

JobSizing

Returns:

The cores the job occupies and the memory it holds.

Raises:

FileNotFoundError – If the archive cannot be read, in which case the job that reads it cannot run.

ataraxis_video_system.orchestration.size_job(job)

Sizes one prepared job from the archive it reads.

Notes

Reads the archive’s zip directory and its file metadata alone, decoding no message.

Parameters:

job (JobDescriptor) – The prepared job to size.

Return type:

tuple[JobDescriptor, JobSizing, ArchiveFootprint]

Returns:

The job carrying its resolved width, the resources the sizing produced, and the archive footprint they follow from, in that order.

Raises:

FileNotFoundError – If the archive cannot be read, in which case the job that reads it cannot run.

ataraxis_video_system.orchestration.start_execution_session(state)

Publishes one execution state as the session of record and starts the thread that manages it.

Notes

The incumbent test, the publication, and the thread start all happen under one lock. A thread reports itself alive only once it has started, so a state published before its thread runs reads as a finished session. Splitting these steps lets two callers each start a manager and double-commit the host’s cores and memory.

A session whose manager thread has ended is replaced, so a completed or an abandoned batch does not block every later batch.

Parameters:

state (JobExecutionState) – The execution state to publish. Its manager thread is created, recorded, and started here.

Return type:

bool

Returns:

True when this state became the session of record, and False when a live session already holds that place.

ataraxis_video_system.orchestration.jobs.CAMERA_EXTRACTION_JOB_NAME: str = 'camera_timestamp_extraction'

The job name under which camera timestamp extraction is registered in a ProcessingTracker.

Notes

The value is hashed into every persisted job identifier, so changing the string invalidates every identifier a tracker already holds and every identifier a scheduler derived independently.

ataraxis_video_system.orchestration.allocation.CAMERA_EXTRACTION_JOB_CORES: int = 8

The core allocation every parallel camera timestamp extraction job receives.

Notes

Every worker opens the archive itself, so the fixed cost per worker holds as workers are added and the speedup flattens well before the core count. Doubling the allocation past this width returns a few percent of a job’s runtime, and the curve turns over by twenty four workers, where opening the pool costs more than splitting the archive saves.

The allocation also sets how many jobs a batch runs at once, because a core budget admits one job per allocation. A wider allocation therefore buys a single recording a little latency at the cost of the concurrency a batch of recordings needs, and this width is the point where a batch of ten still fits one admission wave on a host that reserves a hundred and twenty six cores for it.

ataraxis_video_system.orchestration.allocation._PARALLEL_EXTRACTION_THRESHOLD: int = 35000

The number of data messages an archive has to hold before an extraction job opens a pool to read it.

Notes

Opening a pool costs one spawned child per core, and every child re-imports the package before it reads a message. Below this count the archive is decoded before that fixed cost is repaid, so the parallel path finishes behind the sequential one. The count is the message load at which the two paths finish together, so it moves with the declared core allocation, which sets how many children the pool has to spawn.

This threshold governs whether a pool is opened at all, which is a different decision from the message batching PARALLEL_PROCESSING_THRESHOLD governs inside the archive reader.

ataraxis_video_system.orchestration.allocation.SPAWNED_CHILD_MEMORY_MB: int = 208

The resident memory one spawned child holds before it touches any data, covering the interpreter and the package’s import graph. The term is charged once for a job’s body and once more for each child of the extraction pool it opens, so a job holding a single core and therefore carrying no pool is charged once.

Notes

The figure is resident memory rather than proportional memory. Roughly two fifths of it is pages the readers share, so a batch running many jobs at once holds less than the sum this term charges it.

A child that only reads holds the import graph alone, while a job body also writes its output file and carries the pinned thread pool the write opens. This term covers the wider of the two, so one constant sizes both.

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 GenTL (Harvesters) compatible cameras.

The camera index and the node blacklist are parsed on this group and shared by every subcommand, so they must be given before the subcommand name.

Usage

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

Options

-c, --camera-index <camera_index>

The index of the target camera in the list of all cameras discoverable through the Harvesters interface.

-b, --blacklisted-node <blacklisted_node>

GenICam node name to exclude from the read, dump, and load 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. An explicitly named node passed to ‘configure write’ is always written. Mutually exclusive with –no-blacklist.

Default:

'CustomerIDKey', 'CustomerValueKey', 'TestPattern'

--no-blacklist

Disables all node blacklisting. When set, all ReadWrite nodes are included in the read, dump, and load operations. Mutually exclusive with –blacklisted-node.

dump

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

The output YAML includes every writable (ReadWrite) node that is not blacklisted, with its current value, as well as the camera model and serial number for identity validation.

Usage

axvs configure dump [OPTIONS]

Options

-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 every non-blacklisted writable node from the configuration file to the camera. Always compares the camera model and serial number against the configuration file, warning on a mismatch and aborting instead when –strict is set.

Usage

axvs configure load [OPTIONS]

Options

-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 every writable (ReadWrite) node that is not blacklisted, with its current value.

Usage

axvs configure read [OPTIONS]

Options

-n, --node-name <node_name>

The name of a specific GenICam node to read. If omitted, lists every writable (ReadWrite) node that is not blacklisted.

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. The node is read back over the same connection, since a node that reports ReadWrite access can still coerce the write to its increment or reject it outright.

Usage

axvs configure write [OPTIONS]

Options

-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, unless the AXVS_CTI_PATH environment variable supplies the Producer path for the runtime.

Usage

axvs cti set [OPTIONS]

Options

-f, --file-path <file_path>

Required 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, runtime requirements checking, video session control, GenICam configuration, camera manifest management, log archive assembly, video file validation, recording discovery, 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 the VideoSystem log archives of one recording 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. Targets a single recording and runs its archives one at a time. Each specified source ID must be registered in the recording’s camera manifest and correspond to exactly one archive. Passing a job ID runs that single job alone, which is how an external scheduler dispatches one unit of work. Use the MCP server to orchestrate batches spanning many recordings.

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 root path under which processed output files are written. A camera_timestamps/ subdirectory is created automatically beneath it and holds the processing tracker and every output file.

-id, --job-id <job_id>

The canonical hexadecimal identifier of the single job to run. If provided, runs only the matching job, which is the target an external scheduler names when it dispatches one unit of work.

-s, --specifier <specifier>

Camera source 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. Ignored when a job ID selects the work.

-w, --workers <workers>

The worker processes each job receives. Set to -1 (default) to resolve the width from the archive’s message count, which yields a single worker for a small archive and the declared per-job allocation of 8 cores for a large one.

Default:

-1

-np, --no-progress

Determines whether to suppress the progress bars during timestamp extraction. The progress bars are displayed by default.

Default:

False

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. The frame acquisition timestamp logs, the camera manifest, and the assembled .npz archives are written to an ‘axvs_live_run_data_log’ subdirectory beneath it, which is the path to pass to ‘axvs process –log-directory’.

-m, --monochrome

Determines whether the camera records frames in monochrome (grayscale) or colored spectrum. Applies to the ‘opencv’ and ‘mock’ interfaces only, as the ‘harvesters’ interface takes the color mode from the camera’s own configuration.

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