Processors

Processors run as separate threads in the pipeline, linked by input-output queues.

Processors define a process(snapshot) method that receives a Snap object containing both the input image(s) and the results of previous processors, performs actions on this data, and returns either the same snap or a modified version of it to be processed by later processors in the pipeline.

Processor shared state

In general, processors don't share state to avoid inter-thread locking. But a shared database of gathered information is available as a global_scope property on all of them.

This GlobalScope object contains:

• Shared stage with Actors detected in previous frames.
• A list of cameras, with calibration info.
• A media_timeline with information about playing media to keep track of views and audience.

Available Processors

Module base

Common Processor Parameters

• display (bool): Show processor on a system window.

  • default: False.

• display_extra (bool): Show processor DEBUG output in a window.

  • default: False.

• enabled (bool): Enable processor.

  • default: True.

• max_fps (float): If processing more than this fps, bypass processor (zero or less disables).

  • default: -1.0.

• stream (bool): Show in browser.

  • default: False.

• tags (str): Apply this processor only to boxes with the given tags.

  • default: None.

BoxParallelProcessor

Superclass for a thread-pool parallelizing processor with minimum-interval checking

Parameters

• number_of_workers (int): Number of worker threads.

  • default: 2 (1-64).

• recheck_interval (float): Period of re-measurement (seconds).

  • default: 1.0 (0.0-60.0).

• data_updates (bool): Should we send data updates for each new value.

  • default: False.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

NullProcessor

Pass-through processor: returns the input snap unchanged.

Parameters

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..
  • default: False.

SampleParametersProcessor

Demo processor for all kinds of parameters. Does nothing.

Parameters

• area (area): Area as either px x px or % of the image.

  • default: 0.

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: face.

• float01 (float): Floating point value from 0 to 1.

  • default: 1.0 (0.0-1.0).

• float0inf (float): Floating point value from 0 to some large value.

  • default: 1.0 (0.0-9.9e+99).

• int0_100 (int): Int form 0 to 100.

  • default: 10 (0-100).

• line (line): Line selection.

  • default: [[0, 50], [100, 50]].

• polygon (polygon): Polygon selection.

  • default: [[0, 0], [0, 100], [100, 100], [100, 0]].

• polyline (polyline): Polyline selection.

  • default: [[0, 80], [100, 80], [80, 60]].

• selector (value1|value2|value3): Selector.

  • default: value1.

• square (square): Square selection.

  • default: [[0, 0], [0, 100], [100, 100], [100, 0]].

• string (str): A string value.

  • default: Some value.

• toggle (bool): Toggle Parameter.

  • default: False.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• vector (vector): Vector selection.

  • default: [[0, 50], [100, 50]].

Module boxfilters

BoxAreaFilterProcessor

Filter boxes between the given min/max areas

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: face.

• maxarea (area): Maximum area in pixels or percent of the image of the box to be detected (=width x height).

  • default: 80000 (0-4194304).

• minarea (area): Minimum area in pixels or percent of the image of the box to be detected (=width x height).

  • default: 3000 (0-160000).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

BoxCameraZonesFilterProcessor

Filter person+face+upper_body boxes outside of camera defined zones Person boxes are filtered based on feet position. Face/upper_body boxes are filtered projecting downwards.

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will filter.

  • default: person.

• project_head_down (float): Project N heads downwards to guess feet position to filter out heads.

  • default: 7.0 (0.0-10.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

BoxMergeProcessor

Merges boxes into ComboBox clusters based on their containment.

Parameters

• box_order (face&person&upper_body&blob&hand&head&skeleton&placeholder&combo): Type of boxes in order of containment for the clusters.

  • default: person,skeleton,upper_body,head,face.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

BoxRatioFilterProcessor

Discard boxes whose size ratio (height/width) is below the set value

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will filter.

  • default: person.

• minratio (float): Minumum ratio (height/width) for the box to be detected (e.g. in a face height > width).

  • default: 1.2 (0.0-10.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

DistanceFilterProcessor

Discard tracks whose floor distance to the camera is outside the [min, max] range.

Uses the floor distance already computed by SmoothFeetProcessor and stored on each combo track as _feet_point.dist_ground_to_feet (metres, measured on the ground plane from the camera to the feet). This processor must run AFTER SmoothFeetProcessor so the feet point is available.

Boxes that are not tracks (non TYPE_COMBO) are always passed through unchanged. A track with no valid feet point (distance unknown) is kept unless drop_unknown is enabled.

Parameters

• debug_draw_filtered (bool): Draw a red dashed box + measured distance on tracks dropped by this filter, for visual debugging.

  • default: False.

• drop_unknown (bool): Drop tracks with no valid feet point (unknown distance). When false, such tracks are kept..

  • default: False.

• max_distance (float): Maximum floor distance to the camera (m) for a track to be kept.

  • default: 100.0 (0.0-1000.0).

• min_distance (float): Minimum floor distance to the camera (m) for a track to be kept.

  • default: 0.0 (0.0-1000.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• use_camera_distance (bool): Use straight-line camera-to-feet distance instead of the ground-plane (floor) distance.

  • default: False.

FocalBoxFilterProcessor

Filter bounding boxes by estimated distance to the camera.

When the camera is calibrated (known height + tilt), distance is the true ground distance obtained by back-projecting the box onto the floor plane. Otherwise it falls back to the pinhole optical-axis depth Z = f_y * H / h_px, assuming an average adult stature (~1.70 m), head crown-to-chin (~0.24 m) or face brow-to-chin (~0.20 m) height.

Supported box types: face, head, person, skeleton, upper_body and combo (a combo delegates to the best contained sub-box). Other types pass through untouched.

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will filter.

  • default: combo.

• exp_head_height (float): Expected average height of a face (brow-to-chin) in meters.

  • default: 0.2 (0.05-0.5).

• exp_person_height (float): Expected average height of a person in meters.

  • default: 1.7 (1.0-3.0).

• max_distance (float): Discard boxes farther than this distance (m).

  • default: 5.0 (0.0-1000.0).

• min_distance (float): Discard boxes closer than this distance (m).

  • default: 0.0 (0.0-1000.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

HeadBoxFilterProcessor

Filter bounding boxes by estimated distance to the camera calculated from the HEAD box only.

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will filter.

  • default: combo.

• coast_max_sec (float): Reuse the last head pose for at most this long after the last real measurement (s); 0 disables coasting.

  • default: 0.34 (0.0-10.0).

• distance_jump (float): Distance EMA spike-gate: reject jumps larger than this (m).

  • default: 0.5 (0.0-1000.0).

• distance_smooth_sec (float): EMA time constant for the distance reading (s); 0 disables distance smoothing.

  • default: 0.3 (0.0-10.0).

• filter_args (dict): Filter init arguments.

  • default: {}.

• head_box_smooth_sec (float): EMA time constant for pre-calculation head-box smoothing, traced as d_hbox (0 disables).

  • default: 0.3 (0.0-10.0).

• max_age (float): Max age of a feature in seconds.

  • default: 60.0 (0.0-1000.0).

• max_distance (float): Discard boxes farther than this distance (m).

  • default: 5.0 (0.0-1000.0).

• min_distance (float): Discard boxes closer than this distance (m).

  • default: 0.0 (0.0-1000.0).

• skeleton_gate (bool): Drop the head-pose correction when the skeleton facing class contradicts the pose yaw (front vs back); fall back to base head height. False applies the pose uncorrected..

  • default: True.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

SkeletonsToBoxesProcessor

Convert skeletons to face+body boxes, and discard them

Parameters

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• use_face (bool): Use face points to generate a face box.

  • default: False.

ZoneExclusionProcessor

Discard boxes whose contact point (center, top-center, bottom-center) is inside any "exclude" contour

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo|any): Type of boxes this processor will filter.

  • default: any.

• contact_point (center|top_middle|bottom_middle|head|feet): Point to check for presence inside/outside the contour.

  • default: center.

• filter_criteria (point_inside|area_intersection): Filter criteria: point inside or area intersection minimum percent.

  • default: point_inside.

• min_area_percent (float): Minimum intersection percentage for the box to be considered for exclusion.

  • default: 0.0 (0.0-100.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Module camera

CameraFloorDrawingProcessor

Draws a projection of the xy camera plane onto the current snapshot.

Parameters

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..
  • default: False.

CameraIntrinsicCalibrationProcessor

Calibrate a camera intrinsic parameters using a checkerboard pattern.

Parameters

• grid_x (int): Grid x size.

  • default: 10 (1-100).

• grid_y (int): Grid x size.

  • default: 7 (1-100).

• max_rms_error (float): Max. RMS error in calibration.

  • default: 2.0 (0.0-200.0).

• min_points (int): Minimum number of captured points.

  • default: 50 (1-500).

• recalibrate (bool): Recalibrate camera trigger calibration.

  • default: False.

• square_size_mm (float): Square size in mm.

  • default: 30 (0.0-200.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

CameraParametersProcessor

Adjust the camera extrinsic parameters either by a 1 m. square on the ground or manually.

Parameters

• calculate_square (trigger): Adjust translation and rotation based on the floor square.

  • default: False.

• camera_h (float): Height from the camera to the ground where the square lays.

  • default: 2.0 (-50.0-50.0).

• meter_square (polygon): A square of 1m sitting at 3m.

  • default: [].

• position_x (float): Camera X position.

  • default: 0.0 (-1000.0-1000.0).

• position_y (float): Camera Y position.

  • default: 0.0 (-1000.0-1000.0).

• position_z (float): Camera Z position.

  • default: 0.0 (-1000.0-1000.0).

• rotation_x (float): Camera X angle in degrees.

  • default: 0.0 (-360.0-360.0).

• rotation_y (float): Camera Y angle in degrees.

  • default: 0.0 (-360.0-360.0).

• rotation_z (float): Camera Z angle in degrees.

  • default: 0.0 (-360.0-360.0).

• save_calibration (trigger): Save current calibration parameters.

  • default: False.

• save_calibration_file (str): File where to save calibration parameters.

  • default: calibration.json.

• square_d (float): Distance to the calibration square.

  • default: 3.0 (0.1-20.0).

• square_l (float): Length in meters of the side of the calibration square.

  • default: 1.0 (0.1-20.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

CameraZonesAnnotatingProcessor

Draws contours and gates on the picture.

Parameters

• draw_gate_limits (bool): Draw the gate arming (distance_threshold) and bounce_band radial limit rings around each gate for crossing diagnostics..

  • default: False.

• gate_arm_radius (int): Arming/working radius in px to draw; match GateProcessor distance_threshold..

  • default: 70.

• gate_bounce_radius (int): Bounce-band radius in px to draw; match GateProcessor bounce_band..

  • default: 28.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Scene3DViewerProcessor

Render a synthetic 3D scene window showing floor contours and tracked feetpoints.

Parameters

• gaze_cone_half_angle_deg (float): Half-angle in degrees used to render the gaze cone in the synthetic 3D scene.

  • default: 18.0 (0.0-45.0).

• gaze_cone_length_m (float): Length in meters of the gaze cone in the synthetic 3D scene.

  • default: 0.9 (0.1-5.0).

• gaze_vector_length_m (float): Length in meters of the gaze direction vector in the synthetic 3D scene.

  • default: 0.9 (0.2-10.0).

• grid_step_m (float): Spacing of the synthetic ground grid in meters.

  • default: 0.5 (0.1-5.0).

• max_actor_height_m (float): Maximum actor height used by the synthetic scene renderer.

  • default: 2.2 (1.2-3.5).

• max_world_distance_m (float): Clamp contour/gate backprojection to this floor distance from the camera.

  • default: 25.0 (1.0-100.0).

• min_actor_height_m (float): Minimum actor height used by the synthetic scene renderer.

  • default: 1.0 (0.5-2.5).

• mirror_coordinates (bool): Mirror synthetic scene coordinates horizontally around the camera center.

  • default: False.

• scene_height (int): Height in pixels of the synthetic 3D scene window.

  • default: 720 (240-2160).

• scene_margin_px (int): Outer padding for the synthetic 3D scene.

  • default: 48 (0-400).

• scene_width (int): Width in pixels of the synthetic 3D scene window.

  • default: 960 (320-3840).

• show_camera (bool): Draw the calibrated camera position on the synthetic 3D scene.

  • default: True.

• show_gaze (bool): Draw head marker, gaze vector and cone when head pose is available.

  • default: True.

• show_grid (bool): Draw a floor grid on the synthetic 3D scene.

  • default: True.

• show_labels (bool): Draw labels for actors and contours on the synthetic 3D scene.

  • default: True.

• show_screen (bool): Draw the calibrated screen plane on the synthetic 3D scene.

  • default: True.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• vertical_scale (float): Vertical exaggeration used for actor columns.

  • default: 1.0 (0.2-3.0).

• view_iso_deg (float): Isometric projection angle for the synthetic 3D scene.

  • default: 30.0 (10.0-60.0).

• view_rotation_deg (float): Rotation of the synthetic 3D scene around the floor plane.

  • default: 20.0 (-180.0-180.0).

Module comm

BoxToSimulatedMQTTProcessor

Publisher processor that outputs different box events to different MQTT paths

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: blob.

• send_falloff (float): Seconds of falloff after sending event.

  • default: 2 (0-100).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• trigger_class (str): Class of the trigger.

  • default: sensor.

• trigger_id (str): Id of the trigger.

  • default: 1.

MQTTPublishingProcessor

Publisher processor that outputs different box events to different MQTT paths

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: person.

• minimal (bool): Only send box and hands, reducing packet size.

  • default: False.

• send_biggest_n (int): Only send N biggest boxes.

  • default: 0 (0-100).

• skel_send (str): Comma separated parts to send (hands,feet,chest) or 'none'.

  • default: hands.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

MessagingProcessor

Send (MQTT) messages for all entering and exiting Boxes. Message payload is of the form:

    {
        "sent-by": "messaging",
        "class": "box",
        "action": "in|out",
        "boxtype": "face|person|blob|head",
        "id": "abcdefg",
        "tags": ["tag1", "tag2", "tag3"],
        "camera": "camera name"
    }

Parameters

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..
  • default: False.

OSCPublishingProcessor

Publisher processor that outputs different box events to different OSC messages

Parameters

• box_state (any|entered): Only emit boxes in this stage state.

  • default: any.

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: face.

• target_host (str): Target host for OSC messages.

  • default: 127.0.0.1.

• target_port (int): Target port of OSC messages.

  • default: 15000.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

SingleTargetMQTTPublishingProcessor

Publisher processor that outputs different box events to different MQTT paths

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: person.

• minimal (bool): Only send box and hands, reducing packet size.

  • default: False.

• send_criteria (center|biggest): Only send center/biggest box.

  • default: biggest.

• skel_send (str): Comma separated parts to send (hands,feet,chest) or 'none'.

  • default: hands.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

StageOSCPublishingProcessor

Publisher processor that outputs different box events to different OSC messages

Parameters

• box_state (any|entered|entering|exiting|exited): Only emit boxes in this stage state.

  • default: entered.

• target_host (str): Target host for OSC messages.

  • default: 127.0.0.1.

• target_port (int): Target port of OSC messages.

  • default: 15000.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

StageTUIOPublishingProcessor

Publisher processor that outputs different box events to different TUIO messages

Parameters

• box_state (any|entered|entering|exiting|exited): Only emit boxes in this stage state.

  • default: entered.

• max_skeleton_speed (float): Maximum speed accepted to send skeleton hands.

  • default: 0.2 (0.0-1000.0).

• skel_send (hands|chest|feet|full): Blob(s) to send for skeletons.

  • default: hands.

• target_host (str): Target host for TUIO messages.

  • default: 127.0.0.1.

• target_port (int): Target port of TUIO messages.

  • default: 15000.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

TUIOPublishingProcessor

Publisher processor that outputs different box events to different TUIO messages

Parameters

• box_state (any|entered): Only emit boxes in this stage state.

  • default: any.

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: face.

• image_path (str): Path where to dump snap images as FSEQ.jpg files (if set).

  • default: .

• max_skeleton_speed (float): Maximum speed accepted to send skeleton hands.

  • default: 0.2 (0.0-1000.0).

• skel_send (hands|chest|feet|full): Blob(s) to send for skeletons.

  • default: hands.

• target_host (str): Target host for TUIO messages.

  • default: 127.0.0.1.

• target_port (int): Target port of TUIO messages.

  • default: 15000.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

VirtualCamProcessor

Outputs video frames to a virtual camera device

Parameters

• annotate (bool): Annotate the image with detection results.

  • default: False.

• clip_h (int): Crop height from the center of the image (zero disables).

  • default: 0 (0-32000).

• clip_w (int): Crop width from the center of the image (zero disables).

  • default: 0 (0-32000).

• device (str): Device parameter for pyvirtualcam (default automatic).

  • default: None.

• draw_floor (bool): Draw camera calibration floor on the image.

  • default: False.

• virtualcam_driver (auto|v4l2loopback|obs|unitycapture): Force driver for the camera.

  • default: auto.

• scale (float): Downscale the frame by this factor before sending (1.0 = full size). Unlike clip_w/clip_h, which crop away the edges, this keeps the whole field of view -- useful because the driver hands consumers a smaller frame anyway, so full-resolution bytes are discarded downstream..

  • default: 1.0 (0.1-1.0).

• target_camera (str): For multicamera, camera name to send to the virtual camera.

  • default: None.

• target_fps (int): Target FPS rate of the Virtual Camera.

  • default: 15 (5-60).

• timecode (bool): Burn a machine-readable frame-number marker into the top-left corner, for measuring end-to-end display latency.

  • default: False.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

ZContoursProcessor

From the Z buffer, generate a mask between distance ranges. Also, calculate normals at every point and send the resulting mask to virtual camera.

Parameters

• virtualcam_device (str): Device path (e.g. /dev/video12) for the camera.

  • default: None.

• virtualcam_driver (auto|v4l2loopback|obs|unitycapture): Force driver for the camera.

  • default: auto.

• max_z_threshold (int): Maximum z if using depth plane (mm).

  • default: 3000 (0-32768).

• min_z_threshold (int): Minimum z if using depth plane (mm).

  • default: 1000 (0-32768).

• target_fps (int): Target FPS rate of the Virtual Camera.

  • default: 15 (5-60).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Module detect

BlobsDetectorProcessor

Substract background and detect blobs on the image

Parameters

• closing_kernel_size (int): Pixel radius for the closing used to reduce small dots (0 disables).

  • default: 6 (0-100).

• max_box_area (float): Maximum area of a detected blob.

  • default: 1000000 (0.0-9.99e+100).

• max_box_ratio (float): Maximum width/height ratio of a detected blob.

  • default: 4.0 (0.0-9.99e+100).

• max_z_threshold (int): Maximum z if using depth plane.

  • default: 5000 (0-32768).

• min_box_area (float): Minimum area of a detected blob.

  • default: 100 (0.0-9.99e+100).

• min_box_ratio (float): Minimum width/height ratio of a detected blob.

  • default: 0.0 (0.0-10).

• min_z_threshold (int): Minimum z if using depth plane.

  • default: 0 (0-32768).

• opening_kernel_size (int): Pixel radius for the opening used to reduce small dots (0 disables).

  • default: 6 (0-100).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• plane (rgb|z): Color plane to use.

  • default: z.

BoxCounterProcessor

No description

Parameters

• area_name (str): Name of the counter area.

  • default: Count Area.

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: face.

• count_chunk_size (int): Number of samples to accumulate before emitting a count event.

  • default: 100.

• outlier_filter_percentile (float): Percentile to filter outliers out (zero disables).

  • default: 0.1 (0.0-1.0).

• report_post_url (str): URL where to POST counter updates.

  • default: None.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

BoxFinderProcessor

Detect bounding boxes for a single class of objects, with optional filtering by area and ratio.

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: face.

• contour (square): Area of the image where to detect.

  • default: [].

• filter_out_iou (float): Filter out boxes overlapping intersection-over-union more than the value (zero disables).

  • default: 0.4 (0.0-1.0).

• maxarea (area): Maximum area in pixels of the box to be detected (=width x height).

  • default: 80000 (0-4194304).

• minarea (area): Minimum area in pixels of the box to be detected (=width x height).

  • default: 3000 (0-160000).

• minratio (float): Minumum ratio (height/width) for the box to be detected (e.g. in a face height > width).

  • default: 1.2 (0.0-10.0).

• threshold (float): Threshold of acceptance for the network detection.

  • default: 0.5 (0.0-1.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Networks

• Network box_finder, defaults to FaceDetectionNetwork.

ClassDetectionProcessor

Run the given multiclass detector on the image, producing boxes filtered by minimum confidence.

Parameters

• bottom_crop (int): Bottom crop area for detection.

  • default: 0 (0-4096).

• classes (str): Classes to accept, comma separated (empty = all).

  • default: .

• classes_set (str): Name of the class set (coco, peron-face-hand, yolov8...) or list of comma-separated classes.

  • default: coco.

• maxarea (area): Maximum area in percent of the image or pixel area of the box to be detected (=width x height).

  • default: -1.0 (-1.0-4194304).

• minarea (area): Minimum area in percent of the image or pixel area of the box to be detected (=width x height).

  • default: -1.0 (-1.0-160000).

• policy (nooverlaps|bestofclass|none): Apply a reduction policy of keeping a single item per class, with best score.

  • default: none.

• threshold (float): Threshold of acceptance for the network detection.

  • default: 0.25 (0.0-1.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Networks

• Network class_finder, defaults to SSDLiteObjectDetectionNetwork.

CounterProcessor

No description

Parameters

• area_name (str): Name of the counter area.

  • default: Count Area.

• count_chunk_size (int): Number of samples to accumulate before emitting a count event.

  • default: 100.

• outlier_filter_percentile (float): Percentile to filter outliers out (zero disables).

  • default: 0.1 (0.0-1.0).

• report_post_url (str): URL where to POST counter updates.

  • default: None.

• split_mode (none|full): Wether to use sliding window to split the input image in chunks.

  • default: none.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Networks

• Network counter_network, defaults to CLIPCounterNetwork.

DepthBlobDetectorProcessor

Detect blobs in depth image.

Parameters

• blob_area_max (int): Maximum blob area to accept.

  • default: 2097152 (0-16777216).

• blob_area_min (int): Minimum blob area to accept.

  • default: 10 (0-16777216).

• min_distance_between_blobs (int): Minumum distance between blobs.

  • default: 1 (0-2048).

• morph_open_size (int): Size of the opening kernel to filter the depth image.

  • default: 10 (1-100).

• threshold_max (int): Maximum distance threshold.

  • default: 30 (0-255).

• threshold_min (int): Minumum distance threshold.

  • default: 10 (0-255).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

PoseHeadProcessor

Unified person-pose + head-bbox detector.

Runs a single 2-class YOLO pose+head model (e.g. person_pose_head_v1.0) and emits two box streams from one inference: - class 0: person box + 17 keypoints → BoxType.TYPE_SKELETON (configurable) - class 1: head bbox → BoxType.TYPE_HEAD

Replaces a SkeletonProcessor + ClassDetectionProcessor (heads) pair.

Parameters

• emit_heads (bool): Emit class-1 detections as head boxes.

  • default: True.

• emit_skeleton (bool): Emit class-0 detections as skeleton boxes.

  • default: True.

• head_policy (nooverlaps|none): Reduction policy applied to head detections.

  • default: none.

• identify (bool): Identify (assign id) to the skeletons.

  • default: True.

• invert_lr (bool): Invert left and right keypoints.

  • default: True.

• maxarea_head (area): Maximum area of a head box (-1 = disabled).

  • default: -1 (-1-4194304).

• maxarea_person (area): Maximum area of a person/skeleton box.

  • default: 280000 (-1-4194304).

• minarea_head (area): Minimum area of a head box (-1 = disabled).

  • default: -1 (-1-4194304).

• minarea_person (area): Minimum area of a person/skeleton box.

  • default: 3000 (-1-4194304).

• minpercent (float): Minimum percent (0-1) of valid keypoints to accept a skeleton.

  • default: 0.4 (0.0-1.0).

• person_box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): BoxType assigned to class-0 (person/skeleton) detections.

  • default: skeleton.

• short_raise (bool): Consider wrist higher than elbow a raised hand, else wrist higher than neck.

  • default: True.

• threshold (float): Network confidence threshold.

  • default: 0.3 (0.0-1.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Networks

• Network pose_head_finder, defaults to YOLOV8PoseHeadNetwork.

SkeletonProcessor

Find persons and skeletal keypoints in an image.

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: skeleton.

• identify (bool): Identify (add id) to the skeletons.

  • default: True.

• invert_lr (bool): Invert left and right.

  • default: True.

• maxarea (area): Maximum area as percentage of the image or pixel area of the box to be detected (=width x height).

  • default: 4194304 (-1-4194304).

• minarea (area): Minimum area as percentage of the image or pixel area of the box to be detected (=width x height).

  • default: 2500 (-1-160000).

• minpercent (float): Minumum percent (0-1) of valid keypoints to accept a skeleton.

  • default: 0.4 (0.0-1.0).

• short_raise (bool): Consider wrist higher than elbow a raised hand, else wrist higher than neck.

  • default: True.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Networks

• Network skeleton_finder, defaults to YOLOV8PoseNetwork.

SlidingWindowClassDetectionProcessor

Find classes in the image, as blobs

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will emit.

  • default: head.

• classes (str): Classes to accept, comma separated (empty = all).

  • default: .

• classes_set (str): Name of the class set (coco, peron-face-hand, yolov8...) or list of comma-separated classes.

  • default: coco.

• threshold (float): Threshold of acceptance for the network detection.

  • default: 0.25 (0.0-1.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Networks

• Network class_finder, defaults to SSDLiteObjectDetectionNetwork.

TopDepthBlobProcessor

Scan depth images for blobs between given distances. Used for person detection from a top-mounted looking straight down 3D camera.

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: person.

• calibrated (bool): Check for recalibration.

  • default: False.

• kernelsize (int): Kernel size for opening the detected image.

  • default: 5 (1-255).

• maxarea (float): Maximum area in pixels of the box to be detected (=width x height).

  • default: 10000 (0-10000000).

• max_threshold (float): Maximum threshold for blob detection.

  • default: 256.0 (0.0-255.0).

• metric_unit (float): Divider to convert camera values to meters.

  • default: 1000.

• minarea (float): Minimum area in pixels of the box to be detected (=width x height).

  • default: 20 (0-10000000).

• min_threshold (float): Minimum threshold for blob detection.

  • default: 10.0 (0.0-255.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Networks

• Network box_finder, defaults to TopDepthPersonDetectionNetwork.

Module features

EncoderProcessor

Assigns and recognizes box ids based on vector encodings

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: face.

• maximum_overlap_time (float): Maximum time during which we will assign an id because of a IOU overlap.

  • default: 2.0 (0.0-1.0).

• minimum_distance_weight (float): Minimum weight to consider a cosine distance valid.

  • default: 0.5 (0.0-1.0).

• minimum_overlap_percent (float): Minumum IOU overlap percent to consider two boxes the same.

  • default: 0.4 (0.0-1.0).

• number_of_workers (int): Number of worker threads.

  • default: 2 (1-64).

• purge_less_than_frames (int): Purge identifications only seen less than that number of frames during purge_older_than_secs.

  • default: 20 (0-200).

• purge_older_than_secs (float): Purge identifications older than this and seen purge_less_than_frames.

  • default: 8.0 (0.0-60.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

FaceAgeGenderProcessor

Find age and gender for the snap face boxes, using separate networks for age and gender

Parameters

• number_of_workers (int): Number of worker threads.

  • default: 2 (1-64).

• recheck_interval (float): Period of re-measurement (seconds).

  • default: 1.0 (0.0-60.0).

• data_updates (bool): Should we send data updates for each new value.

  • default: False.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Networks

• Network age, defaults to FaceAgeNetwork.
• Network gender, defaults to FaceGenderNetwork.

FaceAttentionProcessor

Calculate face attention as a percentage of total time looking to the camera surroundings.

Parameters

• number_of_workers (int): Number of worker threads.

  • default: 2 (1-64).

• recheck_interval (float): Period of re-measurement (seconds).

  • default: 1.0 (0.0-60.0).

• data_updates (bool): Should we send data updates for each new value.

  • default: False.

• straight_angle_limit (float): Maximum view angle that is considered being looking straight to the camera.

  • default: 25.0 (0.0-180.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Networks

• Network gaze, defaults to FaceGazeNetwork.
• Network pose, defaults to FacePoseNetwork.

FaceEmotionProcessor

Calculate dominant perceived emotional state

Parameters

• number_of_workers (int): Number of worker threads.

  • default: 2 (1-64).

• recheck_interval (float): Period of re-measurement (seconds).

  • default: 1.0 (0.0-60.0).

• data_updates (bool): Should we send data updates for each new value.

  • default: False.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Networks

• Network emotion, defaults to FaceEmotionNetwork.

FaceEncoderProcessor

Assigns and recognizes box ids based on rotated face encodings

Parameters

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..
  • default: False.

Networks

• Network landmarks, defaults to FaceLandmarksNetwork.
• Network identifier, defaults to FaceReidentificationNetwork.

FaceLandmarksProcessor

Retrieve landmarks and rotated face from the given face boxes in the snap.

Parameters

• number_of_workers (int): Number of worker threads.

  • default: 2 (1-64).

• recheck_interval (float): Period of re-measurement (seconds).

  • default: 1.0 (0.0-60.0).

• save_rotated (bool): Save the rotated, warped face for later processing.

  • default: True.

• data_updates (bool): Should we send data updates for each new value.

  • default: False.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Networks

• Network landmarks, defaults to FaceLandmarksNetwork.

FeatureMergeProcessor

Copies features from blob boxes to the nearest overlapping box of the given type. Decided via IoU matching.

Parameters

• min_iou (float): Minimum overlap needed to assign a class to a box.

  • default: 0.1 (0.0-1.0).

• target_box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes where the classes will be assigned to.

  • default: person.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

FrontFacingCounterProcessor

Approximate attention based on whether the face for a given person is detected or not.

Parameters

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..
  • default: False.

HeadPoseProcessor

Calculate head pose (rotation respect to the camera) Sets the "head_pose" Rotation feature on the boxes. Sets the "_yaw_pitch_roll" feature on the boxes.

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: head.

• smooth_angles (bool): Smooth angles.

  • default: True.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Networks

• Network pose, defaults to FacePoseNetwork.

PersonAgeGenderProcessor

Find age and gender for the given face boxes

Parameters

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..
  • default: False.

Networks

• Network age_gender, defaults to FaceAgeGenderVoloNetwork.

ScreenAttentionProcessor

Calculate face attention as a percentage of total time looking to the camera surroundings. Requires that boxes have a "_head_pose" feature set (set by DirectMHPNetwork or similar).

Parameters

• head_pose_bias_auto (bool): Derive yaw bias automatically from the camera extrinsic tilt (calibration.json) instead of head_pose_bias_yaw_deg. Uses the empirical model in src/util/camera_bias.py..

  • default: True.

• head_pose_bias_pitch_deg (float): Additive pitch correction (degrees), applied before smoothing..

  • default: 0.0 (-45.0-45.0).

• head_pose_bias_roll_deg (float): Additive roll correction (degrees), applied before smoothing..

  • default: 0.0 (-45.0-45.0).

• head_pose_bias_yaw_deg (float): Additive yaw correction (degrees), applied before smoothing. 0 = no correction..

  • default: 0.0 (-45.0-45.0).

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: head.

• fallback_angle (float): Angle at which an unconfigured screen is considered to be being looked at.

  • default: 25.0 (0.0-180.0).

• gaze_cone_coverage_mode (str): 'footprint' = intersection/footprint_area (legacy). 'normalized' = intersection/min(footprint_area, screen_area). Normalized mode is equivalent to footprint at close range and screen-coverage at far range..

  • default: normalized.

• gaze_cone_half_angle_deg (float): Cone half-angle in degrees (cone mode only). Defaults to 8.0 to match DirectMHP yaw MAE. Larger = more tolerant; smaller = stricter..

  • default: 10.0 (0.5-45.0).

• gaze_cone_hit_ratio (float): Cone-footprint overlap threshold in [0, 1] (cone mode only). 0.30 = 30%% of the cone's footprint must land on the screen..

  • default: 0.2 (0.0-1.0).

• gaze_cone_n_samples (int): Number of cone-boundary samples used to form the footprint polygon (cone mode only). 32 balances accuracy vs speed..

  • default: 32 (8-128).

• gaze_debug_csv (bool): Enable per-box CSV logging of gaze-hit intermediate values (slows FPS; for benchmarking)..

  • default: False.

• gaze_hit_mode (ray|cone): Gaze hit-test mode. 'ray' = central-ray intersection (legacy). 'cone' = flashlight-cone footprint overlap test..

  • default: cone.

• gaze_margin (float): Multiplier on screen half-size used for gaze-hit tolerance (1.0 = exact screen edges)..

  • default: 1.5 (0.1-5.0).

• scene_bias_pitch_deg (float): Per-scene pitch correction (degrees), summed with the pitch from head_pose_bias_auto / head_pose_bias_pitch_deg. Default 0 = no overlay..

  • default: 0.0 (-45.0-45.0).

• scene_bias_yaw_deg (float): Per-scene yaw correction (degrees), summed with the yaw from head_pose_bias_auto / head_pose_bias_yaw_deg. Produced by tools/calibrate_scene_bias.py. Default 0 = no overlay..

  • default: 0.0 (-45.0-45.0).

• smooth_angles (bool): Enable circular-mean smoothing of yaw/pitch/roll before gaze evaluation..

  • default: False.

• smooth_angles_min_samples (int): Minimum samples in window before smoothing kicks in; below this, raw angle passes through..

  • default: 3 (1-60).

• smooth_angles_window_sec (float): Time window (seconds) for AngleSmoother. FPS-invariant: 0.2s covers ~5 frames @25fps..

  • default: 0.2 (0.0-5.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

SelectiveAgeGenderProcessor

Detect a single candidate age and gender, picking one per frame from the global stage in order of descending face box area.

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes to process.

  • default: face.

• keypoint_min_conf (float): Minimum per-keypoint confidence to trust a skeleton keypoint for body-orientation derivation..

  • default: 0.3.

• lock_pitch_deg (float): Additional lock condition on pitch: a PASS only locks the commit if |ema_pitch| is also below this. Prevents downward-looking misclassifications from anchoring the gender result. Set to 90 to disable..

  • default: 90.0.

• lock_quality_deg (float): Initial-lock threshold: an actor's first PASS only locks the commit if |ema_yaw| is below this. Earlier PASSes still commit features but don't lock — every subsequent PASS overwrites until a high-quality one arrives and locks. Set to a large value (e.g. 90) to lock on the very first PASS like before..

  • default: 30.0.

• log_raw_pose (bool): Log raw yaw/pitch/roll for every head candidate evaluated each frame. Diagnostic..

  • default: False.

• max_abs_pitch_deg (float): Skip candidate if |pitch| exceeds this (degrees). Only applied when _yaw_pitch_roll is present on the box..

  • default: 50.0.

• max_abs_yaw_deg (float): Skip candidate if |yaw| exceeds this (degrees). Only applied when _yaw_pitch_roll is present on the box..

  • default: 90.0.

• max_abs_yaw_deg_relaxed (float): Relaxed |yaw| gate that applies when the skeleton independently confirms a sideways body pose facing the camera. Falls back to PARAM_MAX_ABS_YAW when no usable skeleton is available..

  • default: 75.0.

• max_ttl (float): Maximum time to live for a box before it is discarded.

  • default: 10.0 (0.0-360.0).

• min_actor_frames (int): Minimum number of frames an actor must be evaluated before age/gender inference is attempted. Filters out ghost tracks that appear briefly. Set to 0 to disable (classify on first eligible frame)..

  • default: 0.

• min_face_size (int): Minimum face size in pixels to classify a face candidate. Set to 0 to disable..

  • default: 64.

• min_frontal_frames (int): Minimum consecutive frames the raw pose must stay within the frontal zone before a candidate is accepted. Resets to 0 whenever the pose gate fires..

  • default: 3.

• min_pose_score (float): Skip candidate if its DirectMHP _pose_score is below this threshold. Default matches DirectMHP's own internal filter; raise via INI to be more conservative..

  • default: 0.5.

• pose_max_jump_deg (float): Reject a raw yaw reading whose circular distance from the previous accepted raw yaw exceeds this. Guards against DirectMHP back-of-head sign flips. Set <=0 to disable..

  • default: 45.0.

• pose_max_consecutive_rejects (int): After this many consecutive velocity-gate rejections, accept the next reading regardless of jump magnitude. Prevents permanent freeze on legitimate fast head turns..

  • default: 5.

• pose_smooth_min_samples (int): Minimum samples before AngleSmoother's MAD outlier check kicks in. Bootstrap frames are accepted..

  • default: 3.

• pose_smooth_window (int): AngleSmoother window size (frames) used purely as a MAD-based outlier validator on raw yaw/pitch/roll per head box.id. The smoothed output is discarded; only the per-sample outlier verdict is consumed..

  • default: 7.

• quality_improve_deg (float): First-PASS-locks: once an actor has a committed age/gender, only overwrite if the new PASS has |ema_yaw| at least this many degrees lower (more frontal) than the locked-in PASS. Set to a large value (e.g. 200) to never overwrite; set to 0 to always overwrite..

  • default: 15.0.

• shoulder_ratio_sideways (float): |L_SHO.x - R_SHO.x| / head_w below which the body is considered sideways (shoulders project narrowly in image space)..

  • default: 0.5.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• use_body (bool): Use face and body picture with the network. Off by default: the current model (mivolo_v1_lagenda.onnx) does not use its body input at all — see devdocs/reports/agegender-mivolo-body-channel-dead.md. Kept (rather than removed) so a working dual-input checkpoint can be dropped in later without redoing this plumbing..

  • default: False.

Networks

• Network age_gender_network, defaults to FaceAgeGenderVoloNetwork.

SelectiveInferenceProcessor

Superclass for processors acting on the global stage. Override and implement a metric to define order of box processing. One box will be processed per frame.

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes to process.

  • default: face.

• max_ttl (float): Maximum time to live for a box before it is discarded.

  • default: 10.0 (0.0-360.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

SelectivePoseBasedAgeGenderProcessor

Detect a single candidate age and gender per frame, gating each head on the attached YOLO skeleton's keypoint confidences and geometry instead of a DirectMHP _yaw_pitch_roll reading.

The gate is a cheap, robust reject decision (not degree-accurate pose):

1. Visibility (hard): nose + BOTH eyes confident. Requiring both eyes removes looking-away and hard profiles at zero marginal cost.
2. Frontality: eye/ear symmetry asymmetry below max_asymmetry.
3. Resolution: inter-ocular pixel distance above min_interocular_px (in addition to the min_face_size box gate in metric(), which runs even earlier and silently excludes a candidate from ever reaching this gate at all).
4. Frontal hysteresis: stay inside the gate min_frontal_frames frames.
5. Best-frame commit-lock: classify once per track, locking on the frame with the lowest asymmetry (asymmetry replaces |yaw| from the DirectMHP-based SelectiveAgeGenderProcessor).

All frontality geometry lives on :meth:Skeleton.head_frontality.

Parameters

• allow_profile (bool): Also accept side/profile views (one eye + its same-side ear confidently visible -- see Skeleton.head_frontality) for classification, not just frontal faces. Off by default (opt-in; introduced alongside a coverage/accuracy benchmark -- see devdocs/reports). A profile PASS is always ranked worse than an accepted frontal one and never locks, so a later frontal read for the same track still wins if one appears..

  • default: False.

• allow_sideways_body (bool): When require_body_facing is on, don't veto a candidate whose shoulders project narrowly in image space (see shoulder_ratio_sideways) as 'facing away' -- a near-perpendicular shoulder line makes the l_sho.x/r_sho.x sign essentially noise, so treat it as a genuine side-on body pose instead of a confident back-turn. Off by default (opt-in, unvalidated at scale); pairs with allow_profile to admit real side-view candidates that require_body_facing otherwise blocks the same way as someone with their back to the camera. Ported from SelectiveAgeGenderProcessor's body_sideways signal..

  • default: False.

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes to process.

  • default: face.

• head_kpt_min_conf (float): Minimum per-keypoint confidence for nose/eye/ear landmarks to be trusted in the frontality gate (tier-1 visibility threshold). Raised from 0.4 after a 3kids/5guys threshold sweep confirmed 0.4 let low-confidence back-of-head keypoints pass as a spuriously symmetric "frontal" face; see devdocs/reports/agegender-independent-mot-accuracy-thisbranch-vs-develophead.md..

  • default: 0.6.

• keypoint_min_conf (float): Minimum per-keypoint confidence to trust a shoulder keypoint for the body-facing corroboration..

  • default: 0.3.

• lock_asymmetry (float): Initial-lock threshold: an actor's first PASS only locks the commit if its asymmetry is below this. Earlier PASSes still commit features but don't lock. Set to a large value (e.g. 1.0) to lock on the very first PASS..

  • default: 0.15 (0.0-1.0).

• log_gate (bool): Log the per-candidate gate decision each frame. Diagnostic..

  • default: False.

• max_asymmetry (float): Skip candidate if its eye/ear frontality asymmetry (0=frontal, 1=profile) exceeds this. The yaw proxy..

  • default: 0.25 (0.0-1.0).

• max_ttl (float): Maximum time to live for a box before it is discarded.

  • default: 10.0 (0.0-360.0).

• min_actor_frames (int): Minimum number of frames an actor must be evaluated before age/gender inference is attempted. Filters out ghost tracks that appear briefly. Set to 0 to disable..

  • default: 0.

• min_face_size (int): Minimum face size in pixels to classify a face candidate. Set to 0 to disable. Lowered from 64 to 30 -- at 64 this silently excluded candidates (no log tag, rejected in metric() before process_candidate ever runs); see the fvstore4 PID 6 investigation in devdocs/reports..

  • default: 30.

• min_frontal_frames (int): Minimum consecutive frames the pose must stay within the frontal gate before a candidate is accepted. Resets to 0 whenever the gate fires..

  • default: 3.

• min_interocular_px (int): Skip candidate if inter-ocular distance (px) is below this usable-resolution floor. 0 disables (rely on min_face_size)..

  • default: 15.

• quality_improve (float): First-PASS-locks: once an actor has a committed age/gender, only overwrite if the new PASS asymmetry is at least this much lower (more frontal) than the locked one. Set to 0 to always overwrite..

  • default: 0.03 (0.0-1.0).

• require_body_facing (bool): Reject a candidate when the skeleton shoulders confidently indicate the body faces AWAY from the camera (subject's left shoulder appears on the camera's left). The face keypoints can still fire on a turned/back head, so this kills back-of-head admits the frontality metric alone lets through. Skipped when no confident shoulder pair is available..

  • default: True.

• shoulder_ratio_sideways (float): |L_SHO.x - R_SHO.x| / box width below which the body is considered genuinely side-on rather than confidently facing away. Only consulted when allow_sideways_body is on. Matches SelectiveAgeGenderProcessor's shoulder_ratio_sideways default..

  • default: 0.5.

• strict_body_facing (bool): When require_body_facing is also on, reject unless the shoulders CONFIRM facing-camera (not just 'not confirmed facing away'). Closes the gap where no confident shoulder pair is available at all -- the exact situation the 3kids back-of-head false-frontal read slipped through in (see devdocs/reports/agegender-3kids-gender-accuracy-fixes.md). Off by default: this is a stricter, unvalidated-at-scale opt-in that trades coverage (candidates with occluded/out-of-frame shoulders get rejected too) for safety against this class of false positive..

  • default: False.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• use_body (bool): Use face and body picture with the network. Off by default: the current model (mivolo_v1_lagenda.onnx) does not use its body input at all — see devdocs/reports/agegender-mivolo-body-channel-dead.md. Kept (rather than removed) so a working dual-input checkpoint can be dropped in later without redoing this plumbing..

  • default: False.

• vote_commit (bool): Pool the first vote_max_samples PASS frames per actor and commit the frontality-weighted majority gender + weighted median age, instead of taking whichever single frame scored the best asymmetry. Best-frame commit lets one marginally more frontal frame overwrite a correct categorical label (observed M->F relocks on 5guys and gelateria2). Off by default..

  • default: False.

• vote_max_samples (int): Inference budget per actor when vote_commit is on. Each MiVOLO v2 call costs ~100ms-1s, so this is a hard cap: once spent the actor stops inferring entirely. Gender is already 100% on the benchmark set at 2; measured fps is flat up to 20 (the gate admits few enough frames that the budget rarely binds), so this is set for age, which is the metric that actually moves..

  • default: 3 (1-50).

Networks

• Network age_gender_network, defaults to FaceAgeGenderVoloNetwork.

Module filters

FeatureFilterProcessor

Filter the given feature using the given parameters.

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Box type to process features for.

  • default: combo.

• feature_id (str): Feature ID to filter.

  • default: _head_pose.

• filter_args (dict): Filter init arguments.

  • default: {}.

• filter_type (float|vector|angle|quaternion): Filter type to apply.

  • default: angle.

• max_age (float): Max age of a feature in seconds.

  • default: 60.0 (0.0-1000.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Module globalstage

ActorAgeGenderProcessor

Detect a single candidate age and gender, picking one per frame from the global stage in order of descending face box area.

Parameters

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• use_body (bool): Use face and body picture with the network. Off by default: the current model (mivolo_v1_lagenda.onnx) does not use its body input at all — see devdocs/reports/agegender-mivolo-body-channel-dead.md. Kept (rather than removed) so a working dual-input checkpoint can be dropped in later without redoing this plumbing..

  • default: False.

Networks

• Network age_gender_network, defaults to FaceAgeGenderVoloNetwork.

ActorInZoneProcessor

Track boxes hitting into/out of a certain contour

Parameters

• box_position (center|topcenter|bottomcenter): Position on the box to locate inside/outside the area.

  • default: bottomcenter.

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will use for the detection.

  • default: person.

• contour (polygon): Contour Polygon where to detect entrance.

  • default: [].

• contour_name (str): Name of the detection contour.

  • default: contour.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

ActorMultiZoneProcessor

Preserve current and previous zones of an actor. Needs "_gate_contour" feature to be set by GateProcessor. Sets actor.features["current_zone"] and actor.features["last_zone"]

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will use for the detection.

  • default: combo.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

StageLoaderProcessor

Load IDENTIFIED person and face boxes into actors

Parameters

• actor_box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of actor boxes to use as actor basis.

  • default: person.

• debug_boxes (bool): Generate debug boxes for annotation.

  • default: True.

• exit_time_interval (float): Time to wait to consider an actor out of stage.

  • default: 6.0 (0.0-600).

• ingress_time_interval (float): Time to wait to consider an actor in stage.

  • default: 3.0 (0.0-60).

• lost_time_interval (float): Time to wait to consider an actor lost.

  • default: 2.0 (0.0-60).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• track_face_boxes (bool): Add identified faces to actors.

  • default: True.

StageReadingProcessor

Superclass for processors acting on the global stage. Override and implement a metric to define order of box processing. One box will be processed per frame.

Parameters

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..
  • default: False.

StageReportProcessor

Report stage status and events like actor entrances exits.

Parameters

• debug_boxes (bool): Generate debug boxes for annotation.

  • default: True.

• enable_http (bool): Enable HTTP POSTing of stage to send_status_post_url.

  • default: False.

• enable_mqtt (bool): Enable MQTT sending to user-defined channel send_status_mqtt_channel.

  • default: False.

• is_view_time_interval (float): Minimum attention time to consider presence a view event.

  • default: 2.0 (0.0-60).

• send_status_mqtt_channel (str): Use this MQTT channel instead of the default one for status messages.

  • default: /vision.

• send_status_post_url (str): Send a HTTP POST (JSON) request with the whole stage info every send_status_time_interval..

  • default: http://localhost:8085.

• send_status_time_interval (float): Send a MQTT status packet with the whole stage info every time interval. Zero disables..

  • default: 1.0 (0.0-60.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Module image

ImageCircleCropProcessor

Clip an image region and black out outside. Useful as a preprocessing step to blank outside interferences.

Parameters

• dx (int): Pixels of center x offset.

  • default: 0 (-10000-10000).

• dy (int): Pixels of center x offset.

  • default: 0 (-10000-10000).

• radius (int): Radius of the circle.

  • default: 300.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• plane (rgb|z): Color plane to use.

  • default: z.

ImageRegionProcessor

Clip an image region and black out outside. Useful as a preprocessing step to blank outside interferences.

Parameters

• contour (polygon): Polygon area of the image to clip.

  • default: [].

• crop (bool): Crop the boundaries of the contour.

  • default: True.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

ZDepthFilterProcessor

Mask the RGB image of the snapshot using the Z (depth) image, clipping between two intervals.

Parameters

• threshold_max (float): Maximum distance threshold.

  • default: 3000 (0-4294967296).

• threshold_min (float): Minumum distance threshold.

  • default: 1000 (0-4294967296).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Module tag

AreaEnterExitProcessor

Track boxes entering/exiting a given area limiting boundary.

Parameters

• area_name (str): Name of the area.

  • default: Area1.

• box_position (center|topcenter|bottomcenter): Position on the box to locate inside/outside the area.

  • default: center.

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will use for the detection.

  • default: head.

• report_post_period (float): Period of POST updates, in seconds.

  • default: 30.0 (0.0-1000.0).

• report_post_url (str): URL where to POST counter updates.

  • default: None.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

AreaHitProcessor

Track tracked boxes hitting into/out of a certain contour/gate

Parameters

• bounce_band (int): Bounce band width where no count is made.

  • default: 28.

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: combo.

• counter_type (contour|gate): Type of counter to use.

  • default: gate.

• distance_threshold (int): Distance threshold to consider a box as entering/exiting.

  • default: 70.

• enable_events (bool): Enable events to be sent to the MQTT broker.

  • default: True.

• contact_point (center|top_middle|bottom_middle|head|feet): Point to check for presence inside/outside the contour.

  • default: feet.

• hysteresis_frames (int): Number of frames to wait before counting a double crossing.

  • default: 8.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

AreaTaggerProcessor

Add a tag to any boxes whose center point (or top center or bottom center) enter the area of interest.

Parameters

• area (polygon): Detection area for tag.

  • default: None.

• box_position (center|topcenter|bottomcenter): Position on the box to locate inside/outside the area.

  • default: bottomcenter.

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: face.

• tag (str): Tag to mark on area hit.

  • default: tag1.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

DoorCounterProcessor

Track boxes passing a door and inside a given contour.

Parameters

• area_limit (int): Maximum number of persons this area allows.

  • default: 10.

• area_name (str): Name of the area this door enters or exits.

  • default: area1.

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: person.

• door (polygon): Polygon representing the entry door.

  • default: [[0, 240], [640, 240]].

• door_name (str): Name of the door.

  • default: door1.

• inside (square): Square to mark the inside area (centroid will be used).

  • default: [[320, 400], [330, 400], [330, 410], [320, 410]].

• remove_timeout (float): Timeout (seconds) for stale boxes to be removed.

  • default: 10.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• track_bottom (bool): Count crossings at the feet, instead of the center of the person box.

  • default: True.

GateProcessor

Tracks entrances and exits of gates and zones. Allows to send events when a box enters/exits a gate or zone.

Parameters

• bounce_band (int): Bounce band width where no count is made.

  • default: 28.

• bounce_band_cm (float): bounce_band in real-world centimetres, converted to pixels local to the gate via the camera calibration. None (default) keeps the pixel constant (bounce_band) unconditionally; requires a calibrated camera to take effect..

  • default: None.

• box_target (center|top_middle|bottom_middle|head|feet): Target point of the box to track.

  • default: feet.

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo|any): Type of boxes this processor will filter.

  • default: combo.

• confirm_max_duration_s (float): A candidate open longer than this without confirming is discarded as inconclusive. A safety valve, not the typical confirmation latency -- a real slow crossing can legitimately take tens of seconds to clear the bounce band (e.g. someone browsing near a zone boundary)..

  • default: 45.0 (0.1-120.0).

• confirm_min_frames (int): Minimum reliable, new-side samples a crossing candidate needs before it can confirm (fire)..

  • default: 2 (1-50).

• counter_type (contour|gate): Type of counter to use.

  • default: gate.

• csv_log (bool): Log crossing events to a CSV file for diagnostics.

  • default: False.

• debug_feet_stages (bool): Store post-Gate-EMA point for debug visualization.

  • default: False.

• diag_csv (bool): Write per-frame diagnostic CSV for contour crossing analysis.

  • default: False.

• distance_threshold (int): Distance threshold to consider a box as entering/exiting.

  • default: 70.

• distance_threshold_cm (float): distance_threshold in real-world centimetres, converted to pixels local to the gate via the camera calibration. None (default) keeps the pixel constant (distance_threshold) unconditionally; requires a calibrated camera to take effect..

  • default: None.

• enable_events (bool): Enable events to be sent to the MQTT broker.

  • default: True.

• head_vel_ema (float): EMA alpha for head velocity smoothing.

  • default: 0.4.

• hysteresis_frames (int): Number of frames to wait before counting a double crossing.

  • default: 8.

• idswap_speed_mps (float): Min world-space feetpoint speed (m/s) implied between a crossing candidate's first and most recent sample for it to be rejected as an ID-swap teleport rather than a genuine crossing. Walking is ~1.5, running ~6; teleports are hundreds..

  • default: 8.0 (0.0-1000.0).

• min_reliable_confidence (float): Minimum Phase 3 reliability (SmoothFeetProcessor) for a sample to count as confirming evidence -- a source-switch frame reads low and is excluded, not voted against the crossing..

  • default: 0.5 (0.0-1.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

TryOnProcessor

Virtual Try-On Processor Sets up a table contour for pick and place actions

Parameters

• bistate_frames (int): Number of frames of delay for pick/place trigger.

  • default: 10.

• box_try_on_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of box where the pickables should be inside-of to be considered a try-on.

  • default: face.

• pickables (str): Comma separated list of pickable classes.

  • default: glasses1,glasses2,glasses3.

• table_contour (polygon): Polygon of the pick/place table.

  • default: [[0.0, 0.5], [1.0, 0.5], [1.0, 1.0], [0.0, 1.0]].

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• use_global_stage (bool): Use boxes from the global stage.

  • default: True.

Module tracking

AreaKalmanTrackingProcessor

Kalman based box tracking with delimited areas of tracking and areas where no trackers are expected to be "born" (e.g. you don't expect someone to appear from nowhere in the middle of the frame).

Parameters

• association_iou (float): Minimum IOU overlap percent for a track to match a tracker.

  • default: 0.3 (0.0-1.0).

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: person.

• max_age (int): Maximum age in FRAMES for a tracklet to survive.

  • default: 50 (0-9999).

• min_hits (int): Minimum number of hits for a tracklet to survive.

  • default: 3 (0-1000).

• no_birth_area (polygon): Area of the image where no trackers should appear.

  • default: [].

• re_association_distance (float): Re-association distance to re-match an unmatched detection.

  • default: 50 (0.0-200).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• tracking_area (polygon): Area of the image where to track.

  • default: [].

BoxOverlapIdentifierProcessor

Assigns and recognizes box ids based on simple IOU overlap

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: person.

• discard_older_than (float): Discard seen boxes when more than (secs) have passed.

  • default: 3 (0-9999).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• update_iou (float): Minumum IOU between frames to preserve stable coordinates.

  • default: 0.8 (0.0-1.0).

FaceInsidePersonIdentifierProcessor

Assigns and recognizes faces inside person boxes and matches their IDs if possible.

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes for the person container (person, topbody, etc).

  • default: person.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

KalmanTrackingProcessor

Basic Kalman-based Tracking Processor

Parameters

• association_iou (float): Minimum IOU overlap percent for a track to match a tracker.

  • default: 0.3 (0.0-1.0).

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: person.

• max_age (float): Maximum age in FRAMES for a tracklet to survive.

  • default: 3.0 (0-999).

• min_hits (int): Minimum number of hits for a tracklet to survive.

  • default: 3 (0-1000).

• re_association_distance (float): Re-association distance to re-match an unmatched detection.

  • default: 50 (0.0-20000).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

ReidentifierProcessor

DNN-embedding based reidentification processor @deprecated

Parameters

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..
  • default: False.

SmoothFeetProcessor

Extract feet position from combo boxes and smooth it.

Parameters

• anchor_ky (float): Vertical anchor offset into head bbox (fraction of h_px).

  • default: 0.2 (0.0-0.5).

• ankle_ema_tolerance_m (float): Max |ankle_height - EMA| (m) to accept ankle-height HEIGHT COMMIT. Additive to the basic plausibility range check. Does NOT gate or delay runtime ankle midpoint feetpoint usage..

  • default: 0.3 (0.05-1.0).

• ankle_floor_offset_m (float): Ankle-to-floor offset in meters (ankles are above ground).

  • default: 0.08 (0.0-0.2).

• ankle_geometry_check_enable (bool): Reject ankle keypoints that fail anatomical sanity (ankle below knee below hip). Defends against pose-net hallucination on occluded ankles..

  • default: True.

• ankle_height_enable (bool): Enable one-shot ankle-based height capture when both ankles visible.

  • default: True.

• ankle_height_max_m (float): Maximum plausible person height (m) for ankle capture.

  • default: 2.2 (1.5-2.5).

• ankle_height_min_m (float): Minimum plausible person height (m) for ankle capture.

  • default: 1.0 (0.5-1.5).

• ankle_midpoint_enable (bool): Use ankle midpoint as highest-priority runtime feetpoint source when reliable.

  • default: True.

• ankle_midpoint_min_conf (float): Minimum per-ankle keypoint confidence for ankle midpoint runtime source.

  • default: 0.5 (0.1-1.0).

• bbox_filter (bool): Enable EMA filtering of head bbox before projection.

  • default: True.

• bestk (bool): Enable best-K sample aggregation for freeze.

  • default: False.

• bestk_k (int): Number of top-quality samples to keep.

  • default: 10 (3-50).

• bestk_min_gap (int): Min frame gap between kept samples (diversity constraint).

  • default: 3 (1-50).

• bestk_min_span (int): Min frame span between first and last top-K sample to allow freeze.

  • default: 30 (5-500).

• bypass_delta_thresh (float): Min screen-space feetpoint jump (px) to trigger source-switch bypass. 0=always bypass.

  • default: 30.0 (0.0-200.0).

• csv_log (bool): Enable CSV debug logging of feet metrics (slows FPS).

  • default: False.

• debug_feet_stages (bool): Store pre-smooth feetpoint for debug visualization.

  • default: False.

• elliptical_width (bool): Use elliptical yaw-aware width model.

  • default: False.

• feet_smooth_adaptive (bool): Use adaptive alpha based on innovation magnitude.

  • default: False.

• feet_smooth_alpha (float): EMA alpha for world-XY feetpoint smoothing (0=OFF, 1=no smoothing).

  • default: 0.18 (0.0-1.0).

• feet_smooth_alpha_max (float): Adaptive: max alpha (light smoothing for large moves).

  • default: 0.5 (0.01-1.0).

• feet_smooth_alpha_min (float): Adaptive: min alpha (heavy smoothing for small moves).

  • default: 0.08 (0.01-1.0).

• feet_smooth_innov_thresh (float): Adaptive: innovation threshold (m) for alpha ramp.

  • default: 0.15 (0.01-1.0).

• freeze_tolerance (float): Freeze variance tolerance as fraction of ref height 1.70m (e.g. 0.10 = 10%).

  • default: 0.05 (0.01-0.3).

• geo_alpha_floor (float): Minimum geo weight floor (lambda) for soft gate alpha scaling.

  • default: 0.0 (0.0-1.0).

• geo_cy_max (float): Max normalized cy (head_cy/img_h) for learning.

  • default: 0.85 (0.0-1.0).

• geo_gate (bool): Enable geometric sample gating for learning (depth + cy).

  • default: False.

• geo_max_depth (float): Max depth (m) for learning samples.

  • default: 15.0 (0.5-50.0).

• geo_soft (bool): Use soft geometric weight instead of hard reject.

  • default: False.

• head_d (float): Head depth front-to-back (m).

  • default: 0.195 (0.12-0.28).

• head_h (float): Head height top-to-chin (m).

  • default: 0.23 (0.15-0.3).

• head_w (float): Head width ear-to-ear (m).

  • default: 0.155 (0.1-0.25).

• h_px_gamma (float): Gamma exponent for H_proj shrinkage curve.

  • default: 0 (0-2.0).

• h_px_ref (float): Reference h_px for distance-aware H_proj shrinkage (0=disabled).

  • default: 0 (0-500).

• h_px_shrink_floor (float): Minimum shrinkage floor (prevents over-correction).

  • default: 0.85 (0.5-1.0).

• max_samples (int): Maximum number of samples to use for feet estimation.

  • default: 15 (0-100).

• min_distance (float): Minimum distance to the camera to consider for feet estimation.

  • default: 10.0 (0-100).

• postfreeze_max_height_jump (float): Max allowed height change (m) when replacing frozen height.

  • default: 0.15 (0.01-0.5).

• postfreeze_quality_margin (float): Min quality score improvement to replace frozen height.

  • default: 0.05 (0.0-0.5).

• postfreeze_refine (bool): Enable post-freeze height refinement (best-accepted-measurement policy).

  • default: False.

• projection_mode (str): Projection mode: hinted, pinhole, hinted_anchor.

  • default: hinted_anchor.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• uncal_head_multiplier (float): Head-heights below head bottom to estimate feet when uncalibrated and no ankles visible.

  • default: 6.0 (1.0-12.0).

• use_model_head_height (bool): Prefer the detector's per-model head height hint (_model_head_height box feature) over head_h when present.

  • default: True.

• yaw_blend (bool): Enable yaw-aware width/height fusion downweighting.

  • default: False.

• yaw_blend_scale (float): Yaw scale for width trust rolloff (higher=faster).

  • default: 1.0 (0.5-3.0).

TaggedDoorCounterProcessor

Track boxes hitting into/out of a certain contour

Parameters

• area_name (str): Name of the area this door enters or exits.

  • default: area1.

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: person.

• remove_timeout (float): Timeout (seconds) for stale boxes to be removed.

  • default: 15.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

TrackingProcessor

Tracking processor with configurable tracker.

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: person.

• coast_frames (int): Frames to keep emitting a predicted (coasted) PLACEHOLDER box for a recently-confirmed track that the tracker stopped returning, so the Stage actor is not retired during a short occlusion gap (0=disabled). Keep <= the tracker's lost window (max_time_lost = fps/30*track_buffer) to avoid double-counting if the subject reappears under a new id..

  • default: 0 (0-100).

• debug_boxes (bool): Generate debug boxes for annotation.

  • default: True.

• default_tracker (basic|ucmc|botsort|bytetrack|ocsort|neotracker|headtracker): Default tracker to use.

  • default: ucmc.

• fallback_tracker (basic|ucmc|botsort|bytetrack|ocsort|neotracker|headtracker): Fallback tracker to use if default tracker cannot be used.

  • default: basic.

• fallback_tracker_params (dict): Extra fallback tracker parameters, passed to constructor.

  • default: {}.

• max_age (float): Maximum life in seconds for a lost tracklet to be removed.

  • default: 5.0 (1.0-20.0).

• preserve_skeletons (bool): Whether or not to preserve skeleton frames.

  • default: False.

• suppress_untracked (bool): Drop boxes whose tracked sub-box was not returned (confirmed) by the tracker, so unconfirmed/lost tracks do not leak downstream carrying an unstable id.

  • default: False.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• tracker_params (dict): Extra tracker parameters, passed to constructor.

  • default: {}.

Networks

• Network reid_embedder, defaults to ReidentificationNetwork.

Module transform

SkeletonToUpperBodyBoxProcessor

Processor that converts skeleton keypoints to upper body bounding boxes.

Parameters

• replace_skeletons (bool): Replace skeletons with upper body boxes.

  • default: False.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Module retired (deprecated)

APIReportingProcessor

Generate HTTP(s) calls on box enter/exit states. @deprecated

Parameters

• api_url (string): Reporting API endpoint.

  • default: http://api.end.pt.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

GridBasedCalibrationProcessor

@deprecated Grid based calibration for Broox Media Player tactile detection. Deprecated product. Do not use.

Parameters

• calibration (showcam|grid|bypass|calibrated): Fire calibration manually.

  • default: bypass.

• max_frame_count (int): Number of frames for calibration.

  • default: 300 (1-10000).

• stream_outfile (string): Full path of the wall.jpg file.

  • default: /tmp/wall.jpg.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

LightTrackingProcessor

@deprecated: Used to control an array of lights to react to people passing.

Parameters

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..
  • default: False.

MappingProcessor

@deprecated Processor that maps coordinates over a 0-1 line over the defined contour

Parameters

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..
  • default: False.

PersonFaceStageProcessor

@deprecated Keep track of ingressing person and face boxes in a virtual "stage", setting its box.state (entering, entered, exiting, exited...) Specialized version of StageProcessor

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: face.

• exit_time_interval (float): Time to wait to consider a box out of stage.

  • default: 3.0 (0.0-60).

• ingress_time_interval (float): Time to wait to consider a box in stage.

  • default: 1.0 (0.0-60).

• is_view_time_interval (float): Minimum attention time to consider presence a view event.

  • default: 2.0 (0.0-60).

• send_status_post_url (str): Send a HTTP POST (JSON) request with the whole stage info every send_status_time_interval..

  • default: None.

• send_status_time_interval (float): Send a MQTT status packet with the whole stage info every time interval. Zero disables..

  • default: 1.0 (0.0-60.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

StageProcessor

@deprecated Keep track of ingressing boxes in a virtual "stage", setting its box.state (entering, entered, exiting, exited...)

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: face.

• exit_time_interval (float): Time to wait to consider a box out of stage.

  • default: 3.0 (0.0-60).

• ingress_time_interval (float): Time to wait to consider a box in stage.

  • default: 1.0 (0.0-60).

• is_view_time_interval (float): Minimum attention time to consider presence a view event.

  • default: 2.0 (0.0-60).

• send_status_post_url (str): Send a HTTP POST (JSON) request with the whole stage info every send_status_time_interval..

  • default: None.

• send_status_time_interval (float): Send a MQTT status packet with the whole stage info every time interval. Zero disables..

  • default: 1.0 (0.0-60.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Module base

Common Processor Parameters

• display (bool): Show processor on a system window.

  • default: False.

• display_extra (bool): Show processor DEBUG output in a window.

  • default: False.

• enabled (bool): Enable processor.

  • default: True.

• max_fps (float): If processing more than this fps, bypass processor (zero or less disables).

  • default: -1.0.

• stream (bool): Show in browser.

  • default: False.

• tags (str): Apply this processor only to boxes with the given tags.

  • default: None.

BoxParallelProcessor

Superclass for a thread-pool parallelizing processor with minimum-interval checking

Parameters

• number_of_workers (int): Number of worker threads.

  • default: 2 (1-64).

• recheck_interval (float): Period of re-measurement (seconds).

  • default: 1.0 (0.0-60.0).

• data_updates (bool): Should we send data updates for each new value.

  • default: False.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

NullProcessor

Pass-through processor: returns the input snap unchanged.

Parameters

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..
  • default: False.

SampleParametersProcessor

Demo processor for all kinds of parameters. Does nothing.

Parameters

• area (area): Area as either px x px or % of the image.

  • default: 0.

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: face.

• float01 (float): Floating point value from 0 to 1.

  • default: 1.0 (0.0-1.0).

• float0inf (float): Floating point value from 0 to some large value.

  • default: 1.0 (0.0-9.9e+99).

• int0_100 (int): Int form 0 to 100.

  • default: 10 (0-100).

• line (line): Line selection.

  • default: [[0, 50], [100, 50]].

• polygon (polygon): Polygon selection.

  • default: [[0, 0], [0, 100], [100, 100], [100, 0]].

• polyline (polyline): Polyline selection.

  • default: [[0, 80], [100, 80], [80, 60]].

• selector (value1|value2|value3): Selector.

  • default: value1.

• square (square): Square selection.

  • default: [[0, 0], [0, 100], [100, 100], [100, 0]].

• string (str): A string value.

  • default: Some value.

• toggle (bool): Toggle Parameter.

  • default: False.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• vector (vector): Vector selection.

  • default: [[0, 50], [100, 50]].

Module boxfilters

BoxAreaFilterProcessor

Filter boxes between the given min/max areas

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: face.

• maxarea (area): Maximum area in pixels or percent of the image of the box to be detected (=width x height).

  • default: 80000 (0-4194304).

• minarea (area): Minimum area in pixels or percent of the image of the box to be detected (=width x height).

  • default: 3000 (0-160000).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

BoxCameraZonesFilterProcessor

Filter person+face+upper_body boxes outside of camera defined zones Person boxes are filtered based on feet position. Face/upper_body boxes are filtered projecting downwards.

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will filter.

  • default: person.

• project_head_down (float): Project N heads downwards to guess feet position to filter out heads.

  • default: 7.0 (0.0-10.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

BoxMergeProcessor

Merges boxes into ComboBox clusters based on their containment.

Parameters

• box_order (face&person&upper_body&blob&hand&head&skeleton&placeholder&combo): Type of boxes in order of containment for the clusters.

  • default: person,skeleton,upper_body,head,face.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

BoxRatioFilterProcessor

Discard boxes whose size ratio (height/width) is below the set value

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will filter.

  • default: person.

• minratio (float): Minumum ratio (height/width) for the box to be detected (e.g. in a face height > width).

  • default: 1.2 (0.0-10.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

DistanceFilterProcessor

Discard tracks whose floor distance to the camera is outside the [min, max] range.

Uses the floor distance already computed by SmoothFeetProcessor and stored on each combo track as _feet_point.dist_ground_to_feet (metres, measured on the ground plane from the camera to the feet). This processor must run AFTER SmoothFeetProcessor so the feet point is available.

Boxes that are not tracks (non TYPE_COMBO) are always passed through unchanged. A track with no valid feet point (distance unknown) is kept unless drop_unknown is enabled.

Parameters

• debug_draw_filtered (bool): Draw a red dashed box + measured distance on tracks dropped by this filter, for visual debugging.

  • default: False.

• drop_unknown (bool): Drop tracks with no valid feet point (unknown distance). When false, such tracks are kept..

  • default: False.

• max_distance (float): Maximum floor distance to the camera (m) for a track to be kept.

  • default: 100.0 (0.0-1000.0).

• min_distance (float): Minimum floor distance to the camera (m) for a track to be kept.

  • default: 0.0 (0.0-1000.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• use_camera_distance (bool): Use straight-line camera-to-feet distance instead of the ground-plane (floor) distance.

  • default: False.

FocalBoxFilterProcessor

Filter bounding boxes by estimated distance to the camera.

When the camera is calibrated (known height + tilt), distance is the true ground distance obtained by back-projecting the box onto the floor plane. Otherwise it falls back to the pinhole optical-axis depth Z = f_y * H / h_px, assuming an average adult stature (~1.70 m), head crown-to-chin (~0.24 m) or face brow-to-chin (~0.20 m) height.

Supported box types: face, head, person, skeleton, upper_body and combo (a combo delegates to the best contained sub-box). Other types pass through untouched.

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will filter.

  • default: combo.

• exp_head_height (float): Expected average height of a face (brow-to-chin) in meters.

  • default: 0.2 (0.05-0.5).

• exp_person_height (float): Expected average height of a person in meters.

  • default: 1.7 (1.0-3.0).

• max_distance (float): Discard boxes farther than this distance (m).

  • default: 5.0 (0.0-1000.0).

• min_distance (float): Discard boxes closer than this distance (m).

  • default: 0.0 (0.0-1000.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

HeadBoxFilterProcessor

Filter bounding boxes by estimated distance to the camera calculated from the HEAD box only.

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will filter.

  • default: combo.

• coast_max_sec (float): Reuse the last head pose for at most this long after the last real measurement (s); 0 disables coasting.

  • default: 0.34 (0.0-10.0).

• distance_jump (float): Distance EMA spike-gate: reject jumps larger than this (m).

  • default: 0.5 (0.0-1000.0).

• distance_smooth_sec (float): EMA time constant for the distance reading (s); 0 disables distance smoothing.

  • default: 0.3 (0.0-10.0).

• filter_args (dict): Filter init arguments.

  • default: {}.

• head_box_smooth_sec (float): EMA time constant for pre-calculation head-box smoothing, traced as d_hbox (0 disables).

  • default: 0.3 (0.0-10.0).

• max_age (float): Max age of a feature in seconds.

  • default: 60.0 (0.0-1000.0).

• max_distance (float): Discard boxes farther than this distance (m).

  • default: 5.0 (0.0-1000.0).

• min_distance (float): Discard boxes closer than this distance (m).

  • default: 0.0 (0.0-1000.0).

• skeleton_gate (bool): Drop the head-pose correction when the skeleton facing class contradicts the pose yaw (front vs back); fall back to base head height. False applies the pose uncorrected..

  • default: True.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

SkeletonsToBoxesProcessor

Convert skeletons to face+body boxes, and discard them

Parameters

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• use_face (bool): Use face points to generate a face box.

  • default: False.

ZoneExclusionProcessor

Discard boxes whose contact point (center, top-center, bottom-center) is inside any "exclude" contour

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo|any): Type of boxes this processor will filter.

  • default: any.

• contact_point (center|top_middle|bottom_middle|head|feet): Point to check for presence inside/outside the contour.

  • default: center.

• filter_criteria (point_inside|area_intersection): Filter criteria: point inside or area intersection minimum percent.

  • default: point_inside.

• min_area_percent (float): Minimum intersection percentage for the box to be considered for exclusion.

  • default: 0.0 (0.0-100.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Module camera

CameraFloorDrawingProcessor

Draws a projection of the xy camera plane onto the current snapshot.

Parameters

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..
  • default: False.

CameraIntrinsicCalibrationProcessor

Calibrate a camera intrinsic parameters using a checkerboard pattern.

Parameters

• grid_x (int): Grid x size.

  • default: 10 (1-100).

• grid_y (int): Grid x size.

  • default: 7 (1-100).

• max_rms_error (float): Max. RMS error in calibration.

  • default: 2.0 (0.0-200.0).

• min_points (int): Minimum number of captured points.

  • default: 50 (1-500).

• recalibrate (bool): Recalibrate camera trigger calibration.

  • default: False.

• square_size_mm (float): Square size in mm.

  • default: 30 (0.0-200.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

CameraParametersProcessor

Adjust the camera extrinsic parameters either by a 1 m. square on the ground or manually.

Parameters

• calculate_square (trigger): Adjust translation and rotation based on the floor square.

  • default: False.

• camera_h (float): Height from the camera to the ground where the square lays.

  • default: 2.0 (-50.0-50.0).

• meter_square (polygon): A square of 1m sitting at 3m.

  • default: [].

• position_x (float): Camera X position.

  • default: 0.0 (-1000.0-1000.0).

• position_y (float): Camera Y position.

  • default: 0.0 (-1000.0-1000.0).

• position_z (float): Camera Z position.

  • default: 0.0 (-1000.0-1000.0).

• rotation_x (float): Camera X angle in degrees.

  • default: 0.0 (-360.0-360.0).

• rotation_y (float): Camera Y angle in degrees.

  • default: 0.0 (-360.0-360.0).

• rotation_z (float): Camera Z angle in degrees.

  • default: 0.0 (-360.0-360.0).

• save_calibration (trigger): Save current calibration parameters.

  • default: False.

• save_calibration_file (str): File where to save calibration parameters.

  • default: calibration.json.

• square_d (float): Distance to the calibration square.

  • default: 3.0 (0.1-20.0).

• square_l (float): Length in meters of the side of the calibration square.

  • default: 1.0 (0.1-20.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

CameraZonesAnnotatingProcessor

Draws contours and gates on the picture.

Parameters

• draw_gate_limits (bool): Draw the gate arming (distance_threshold) and bounce_band radial limit rings around each gate for crossing diagnostics..

  • default: False.

• gate_arm_radius (int): Arming/working radius in px to draw; match GateProcessor distance_threshold..

  • default: 70.

• gate_bounce_radius (int): Bounce-band radius in px to draw; match GateProcessor bounce_band..

  • default: 28.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Scene3DViewerProcessor

Render a synthetic 3D scene window showing floor contours and tracked feetpoints.

Parameters

• gaze_cone_half_angle_deg (float): Half-angle in degrees used to render the gaze cone in the synthetic 3D scene.

  • default: 18.0 (0.0-45.0).

• gaze_cone_length_m (float): Length in meters of the gaze cone in the synthetic 3D scene.

  • default: 0.9 (0.1-5.0).

• gaze_vector_length_m (float): Length in meters of the gaze direction vector in the synthetic 3D scene.

  • default: 0.9 (0.2-10.0).

• grid_step_m (float): Spacing of the synthetic ground grid in meters.

  • default: 0.5 (0.1-5.0).

• max_actor_height_m (float): Maximum actor height used by the synthetic scene renderer.

  • default: 2.2 (1.2-3.5).

• max_world_distance_m (float): Clamp contour/gate backprojection to this floor distance from the camera.

  • default: 25.0 (1.0-100.0).

• min_actor_height_m (float): Minimum actor height used by the synthetic scene renderer.

  • default: 1.0 (0.5-2.5).

• mirror_coordinates (bool): Mirror synthetic scene coordinates horizontally around the camera center.

  • default: False.

• scene_height (int): Height in pixels of the synthetic 3D scene window.

  • default: 720 (240-2160).

• scene_margin_px (int): Outer padding for the synthetic 3D scene.

  • default: 48 (0-400).

• scene_width (int): Width in pixels of the synthetic 3D scene window.

  • default: 960 (320-3840).

• show_camera (bool): Draw the calibrated camera position on the synthetic 3D scene.

  • default: True.

• show_gaze (bool): Draw head marker, gaze vector and cone when head pose is available.

  • default: True.

• show_grid (bool): Draw a floor grid on the synthetic 3D scene.

  • default: True.

• show_labels (bool): Draw labels for actors and contours on the synthetic 3D scene.

  • default: True.

• show_screen (bool): Draw the calibrated screen plane on the synthetic 3D scene.

  • default: True.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• vertical_scale (float): Vertical exaggeration used for actor columns.

  • default: 1.0 (0.2-3.0).

• view_iso_deg (float): Isometric projection angle for the synthetic 3D scene.

  • default: 30.0 (10.0-60.0).

• view_rotation_deg (float): Rotation of the synthetic 3D scene around the floor plane.

  • default: 20.0 (-180.0-180.0).

Module comm

BoxToSimulatedMQTTProcessor

Publisher processor that outputs different box events to different MQTT paths

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: blob.

• send_falloff (float): Seconds of falloff after sending event.

  • default: 2 (0-100).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• trigger_class (str): Class of the trigger.

  • default: sensor.

• trigger_id (str): Id of the trigger.

  • default: 1.

MQTTPublishingProcessor

Publisher processor that outputs different box events to different MQTT paths

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: person.

• minimal (bool): Only send box and hands, reducing packet size.

  • default: False.

• send_biggest_n (int): Only send N biggest boxes.

  • default: 0 (0-100).

• skel_send (str): Comma separated parts to send (hands,feet,chest) or 'none'.

  • default: hands.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

MessagingProcessor

Send (MQTT) messages for all entering and exiting Boxes. Message payload is of the form:

    {
        "sent-by": "messaging",
        "class": "box",
        "action": "in|out",
        "boxtype": "face|person|blob|head",
        "id": "abcdefg",
        "tags": ["tag1", "tag2", "tag3"],
        "camera": "camera name"
    }

Parameters

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..
  • default: False.

OSCPublishingProcessor

Publisher processor that outputs different box events to different OSC messages

Parameters

• box_state (any|entered): Only emit boxes in this stage state.

  • default: any.

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: face.

• target_host (str): Target host for OSC messages.

  • default: 127.0.0.1.

• target_port (int): Target port of OSC messages.

  • default: 15000.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

SingleTargetMQTTPublishingProcessor

Publisher processor that outputs different box events to different MQTT paths

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: person.

• minimal (bool): Only send box and hands, reducing packet size.

  • default: False.

• send_criteria (center|biggest): Only send center/biggest box.

  • default: biggest.

• skel_send (str): Comma separated parts to send (hands,feet,chest) or 'none'.

  • default: hands.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

StageOSCPublishingProcessor

Publisher processor that outputs different box events to different OSC messages

Parameters

• box_state (any|entered|entering|exiting|exited): Only emit boxes in this stage state.

  • default: entered.

• target_host (str): Target host for OSC messages.

  • default: 127.0.0.1.

• target_port (int): Target port of OSC messages.

  • default: 15000.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

StageTUIOPublishingProcessor

Publisher processor that outputs different box events to different TUIO messages

Parameters

• box_state (any|entered|entering|exiting|exited): Only emit boxes in this stage state.

  • default: entered.

• max_skeleton_speed (float): Maximum speed accepted to send skeleton hands.

  • default: 0.2 (0.0-1000.0).

• skel_send (hands|chest|feet|full): Blob(s) to send for skeletons.

  • default: hands.

• target_host (str): Target host for TUIO messages.

  • default: 127.0.0.1.

• target_port (int): Target port of TUIO messages.

  • default: 15000.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

TUIOPublishingProcessor

Publisher processor that outputs different box events to different TUIO messages

Parameters

• box_state (any|entered): Only emit boxes in this stage state.

  • default: any.

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: face.

• image_path (str): Path where to dump snap images as FSEQ.jpg files (if set).

  • default: .

• max_skeleton_speed (float): Maximum speed accepted to send skeleton hands.

  • default: 0.2 (0.0-1000.0).

• skel_send (hands|chest|feet|full): Blob(s) to send for skeletons.

  • default: hands.

• target_host (str): Target host for TUIO messages.

  • default: 127.0.0.1.

• target_port (int): Target port of TUIO messages.

  • default: 15000.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

VirtualCamProcessor

Outputs video frames to a virtual camera device

Parameters

• annotate (bool): Annotate the image with detection results.

  • default: False.

• clip_h (int): Crop height from the center of the image (zero disables).

  • default: 0 (0-32000).

• clip_w (int): Crop width from the center of the image (zero disables).

  • default: 0 (0-32000).

• device (str): Device parameter for pyvirtualcam (default automatic).

  • default: None.

• draw_floor (bool): Draw camera calibration floor on the image.

  • default: False.

• virtualcam_driver (auto|v4l2loopback|obs|unitycapture): Force driver for the camera.

  • default: auto.

• scale (float): Downscale the frame by this factor before sending (1.0 = full size). Unlike clip_w/clip_h, which crop away the edges, this keeps the whole field of view -- useful because the driver hands consumers a smaller frame anyway, so full-resolution bytes are discarded downstream..

  • default: 1.0 (0.1-1.0).

• target_camera (str): For multicamera, camera name to send to the virtual camera.

  • default: None.

• target_fps (int): Target FPS rate of the Virtual Camera.

  • default: 15 (5-60).

• timecode (bool): Burn a machine-readable frame-number marker into the top-left corner, for measuring end-to-end display latency.

  • default: False.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

ZContoursProcessor

From the Z buffer, generate a mask between distance ranges. Also, calculate normals at every point and send the resulting mask to virtual camera.

Parameters

• virtualcam_device (str): Device path (e.g. /dev/video12) for the camera.

  • default: None.

• virtualcam_driver (auto|v4l2loopback|obs|unitycapture): Force driver for the camera.

  • default: auto.

• max_z_threshold (int): Maximum z if using depth plane (mm).

  • default: 3000 (0-32768).

• min_z_threshold (int): Minimum z if using depth plane (mm).

  • default: 1000 (0-32768).

• target_fps (int): Target FPS rate of the Virtual Camera.

  • default: 15 (5-60).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Module detect

BlobsDetectorProcessor

Substract background and detect blobs on the image

Parameters

• closing_kernel_size (int): Pixel radius for the closing used to reduce small dots (0 disables).

  • default: 6 (0-100).

• max_box_area (float): Maximum area of a detected blob.

  • default: 1000000 (0.0-9.99e+100).

• max_box_ratio (float): Maximum width/height ratio of a detected blob.

  • default: 4.0 (0.0-9.99e+100).

• max_z_threshold (int): Maximum z if using depth plane.

  • default: 5000 (0-32768).

• min_box_area (float): Minimum area of a detected blob.

  • default: 100 (0.0-9.99e+100).

• min_box_ratio (float): Minimum width/height ratio of a detected blob.

  • default: 0.0 (0.0-10).

• min_z_threshold (int): Minimum z if using depth plane.

  • default: 0 (0-32768).

• opening_kernel_size (int): Pixel radius for the opening used to reduce small dots (0 disables).

  • default: 6 (0-100).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• plane (rgb|z): Color plane to use.

  • default: z.

BoxCounterProcessor

No description

Parameters

• area_name (str): Name of the counter area.

  • default: Count Area.

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: face.

• count_chunk_size (int): Number of samples to accumulate before emitting a count event.

  • default: 100.

• outlier_filter_percentile (float): Percentile to filter outliers out (zero disables).

  • default: 0.1 (0.0-1.0).

• report_post_url (str): URL where to POST counter updates.

  • default: None.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

BoxFinderProcessor

Detect bounding boxes for a single class of objects, with optional filtering by area and ratio.

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: face.

• contour (square): Area of the image where to detect.

  • default: [].

• filter_out_iou (float): Filter out boxes overlapping intersection-over-union more than the value (zero disables).

  • default: 0.4 (0.0-1.0).

• maxarea (area): Maximum area in pixels of the box to be detected (=width x height).

  • default: 80000 (0-4194304).

• minarea (area): Minimum area in pixels of the box to be detected (=width x height).

  • default: 3000 (0-160000).

• minratio (float): Minumum ratio (height/width) for the box to be detected (e.g. in a face height > width).

  • default: 1.2 (0.0-10.0).

• threshold (float): Threshold of acceptance for the network detection.

  • default: 0.5 (0.0-1.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Networks

• Network box_finder, defaults to FaceDetectionNetwork.

ClassDetectionProcessor

Run the given multiclass detector on the image, producing boxes filtered by minimum confidence.

Parameters

• bottom_crop (int): Bottom crop area for detection.

  • default: 0 (0-4096).

• classes (str): Classes to accept, comma separated (empty = all).

  • default: .

• classes_set (str): Name of the class set (coco, peron-face-hand, yolov8...) or list of comma-separated classes.

  • default: coco.

• maxarea (area): Maximum area in percent of the image or pixel area of the box to be detected (=width x height).

  • default: -1.0 (-1.0-4194304).

• minarea (area): Minimum area in percent of the image or pixel area of the box to be detected (=width x height).

  • default: -1.0 (-1.0-160000).

• policy (nooverlaps|bestofclass|none): Apply a reduction policy of keeping a single item per class, with best score.

  • default: none.

• threshold (float): Threshold of acceptance for the network detection.

  • default: 0.25 (0.0-1.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Networks

• Network class_finder, defaults to SSDLiteObjectDetectionNetwork.

CounterProcessor

No description

Parameters

• area_name (str): Name of the counter area.

  • default: Count Area.

• count_chunk_size (int): Number of samples to accumulate before emitting a count event.

  • default: 100.

• outlier_filter_percentile (float): Percentile to filter outliers out (zero disables).

  • default: 0.1 (0.0-1.0).

• report_post_url (str): URL where to POST counter updates.

  • default: None.

• split_mode (none|full): Wether to use sliding window to split the input image in chunks.

  • default: none.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Networks

• Network counter_network, defaults to CLIPCounterNetwork.

DepthBlobDetectorProcessor

Detect blobs in depth image.

Parameters

• blob_area_max (int): Maximum blob area to accept.

  • default: 2097152 (0-16777216).

• blob_area_min (int): Minimum blob area to accept.

  • default: 10 (0-16777216).

• min_distance_between_blobs (int): Minumum distance between blobs.

  • default: 1 (0-2048).

• morph_open_size (int): Size of the opening kernel to filter the depth image.

  • default: 10 (1-100).

• threshold_max (int): Maximum distance threshold.

  • default: 30 (0-255).

• threshold_min (int): Minumum distance threshold.

  • default: 10 (0-255).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

PoseHeadProcessor

Unified person-pose + head-bbox detector.

Runs a single 2-class YOLO pose+head model (e.g. person_pose_head_v1.0) and emits two box streams from one inference: - class 0: person box + 17 keypoints → BoxType.TYPE_SKELETON (configurable) - class 1: head bbox → BoxType.TYPE_HEAD

Replaces a SkeletonProcessor + ClassDetectionProcessor (heads) pair.

Parameters

• emit_heads (bool): Emit class-1 detections as head boxes.

  • default: True.

• emit_skeleton (bool): Emit class-0 detections as skeleton boxes.

  • default: True.

• head_policy (nooverlaps|none): Reduction policy applied to head detections.

  • default: none.

• identify (bool): Identify (assign id) to the skeletons.

  • default: True.

• invert_lr (bool): Invert left and right keypoints.

  • default: True.

• maxarea_head (area): Maximum area of a head box (-1 = disabled).

  • default: -1 (-1-4194304).

• maxarea_person (area): Maximum area of a person/skeleton box.

  • default: 280000 (-1-4194304).

• minarea_head (area): Minimum area of a head box (-1 = disabled).

  • default: -1 (-1-4194304).

• minarea_person (area): Minimum area of a person/skeleton box.

  • default: 3000 (-1-4194304).

• minpercent (float): Minimum percent (0-1) of valid keypoints to accept a skeleton.

  • default: 0.4 (0.0-1.0).

• person_box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): BoxType assigned to class-0 (person/skeleton) detections.

  • default: skeleton.

• short_raise (bool): Consider wrist higher than elbow a raised hand, else wrist higher than neck.

  • default: True.

• threshold (float): Network confidence threshold.

  • default: 0.3 (0.0-1.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Networks

• Network pose_head_finder, defaults to YOLOV8PoseHeadNetwork.

SkeletonProcessor

Find persons and skeletal keypoints in an image.

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: skeleton.

• identify (bool): Identify (add id) to the skeletons.

  • default: True.

• invert_lr (bool): Invert left and right.

  • default: True.

• maxarea (area): Maximum area as percentage of the image or pixel area of the box to be detected (=width x height).

  • default: 4194304 (-1-4194304).

• minarea (area): Minimum area as percentage of the image or pixel area of the box to be detected (=width x height).

  • default: 2500 (-1-160000).

• minpercent (float): Minumum percent (0-1) of valid keypoints to accept a skeleton.

  • default: 0.4 (0.0-1.0).

• short_raise (bool): Consider wrist higher than elbow a raised hand, else wrist higher than neck.

  • default: True.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Networks

• Network skeleton_finder, defaults to YOLOV8PoseNetwork.

SlidingWindowClassDetectionProcessor

Find classes in the image, as blobs

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will emit.

  • default: head.

• classes (str): Classes to accept, comma separated (empty = all).

  • default: .

• classes_set (str): Name of the class set (coco, peron-face-hand, yolov8...) or list of comma-separated classes.

  • default: coco.

• threshold (float): Threshold of acceptance for the network detection.

  • default: 0.25 (0.0-1.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Networks

• Network class_finder, defaults to SSDLiteObjectDetectionNetwork.

TopDepthBlobProcessor

Scan depth images for blobs between given distances. Used for person detection from a top-mounted looking straight down 3D camera.

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: person.

• calibrated (bool): Check for recalibration.

  • default: False.

• kernelsize (int): Kernel size for opening the detected image.

  • default: 5 (1-255).

• maxarea (float): Maximum area in pixels of the box to be detected (=width x height).

  • default: 10000 (0-10000000).

• max_threshold (float): Maximum threshold for blob detection.

  • default: 256.0 (0.0-255.0).

• metric_unit (float): Divider to convert camera values to meters.

  • default: 1000.

• minarea (float): Minimum area in pixels of the box to be detected (=width x height).

  • default: 20 (0-10000000).

• min_threshold (float): Minimum threshold for blob detection.

  • default: 10.0 (0.0-255.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Networks

• Network box_finder, defaults to TopDepthPersonDetectionNetwork.

Module features

EncoderProcessor

Assigns and recognizes box ids based on vector encodings

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: face.

• maximum_overlap_time (float): Maximum time during which we will assign an id because of a IOU overlap.

  • default: 2.0 (0.0-1.0).

• minimum_distance_weight (float): Minimum weight to consider a cosine distance valid.

  • default: 0.5 (0.0-1.0).

• minimum_overlap_percent (float): Minumum IOU overlap percent to consider two boxes the same.

  • default: 0.4 (0.0-1.0).

• number_of_workers (int): Number of worker threads.

  • default: 2 (1-64).

• purge_less_than_frames (int): Purge identifications only seen less than that number of frames during purge_older_than_secs.

  • default: 20 (0-200).

• purge_older_than_secs (float): Purge identifications older than this and seen purge_less_than_frames.

  • default: 8.0 (0.0-60.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

FaceAgeGenderProcessor

Find age and gender for the snap face boxes, using separate networks for age and gender

Parameters

• number_of_workers (int): Number of worker threads.

  • default: 2 (1-64).

• recheck_interval (float): Period of re-measurement (seconds).

  • default: 1.0 (0.0-60.0).

• data_updates (bool): Should we send data updates for each new value.

  • default: False.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Networks

• Network age, defaults to FaceAgeNetwork.
• Network gender, defaults to FaceGenderNetwork.

FaceAttentionProcessor

Calculate face attention as a percentage of total time looking to the camera surroundings.

Parameters

• number_of_workers (int): Number of worker threads.

  • default: 2 (1-64).

• recheck_interval (float): Period of re-measurement (seconds).

  • default: 1.0 (0.0-60.0).

• data_updates (bool): Should we send data updates for each new value.

  • default: False.

• straight_angle_limit (float): Maximum view angle that is considered being looking straight to the camera.

  • default: 25.0 (0.0-180.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Networks

• Network gaze, defaults to FaceGazeNetwork.
• Network pose, defaults to FacePoseNetwork.

FaceEmotionProcessor

Calculate dominant perceived emotional state

Parameters

• number_of_workers (int): Number of worker threads.

  • default: 2 (1-64).

• recheck_interval (float): Period of re-measurement (seconds).

  • default: 1.0 (0.0-60.0).

• data_updates (bool): Should we send data updates for each new value.

  • default: False.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Networks

• Network emotion, defaults to FaceEmotionNetwork.

FaceEncoderProcessor

Assigns and recognizes box ids based on rotated face encodings

Parameters

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..
  • default: False.

Networks

• Network landmarks, defaults to FaceLandmarksNetwork.
• Network identifier, defaults to FaceReidentificationNetwork.

FaceLandmarksProcessor

Retrieve landmarks and rotated face from the given face boxes in the snap.

Parameters

• number_of_workers (int): Number of worker threads.

  • default: 2 (1-64).

• recheck_interval (float): Period of re-measurement (seconds).

  • default: 1.0 (0.0-60.0).

• save_rotated (bool): Save the rotated, warped face for later processing.

  • default: True.

• data_updates (bool): Should we send data updates for each new value.

  • default: False.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Networks

• Network landmarks, defaults to FaceLandmarksNetwork.

FeatureMergeProcessor

Copies features from blob boxes to the nearest overlapping box of the given type. Decided via IoU matching.

Parameters

• min_iou (float): Minimum overlap needed to assign a class to a box.

  • default: 0.1 (0.0-1.0).

• target_box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes where the classes will be assigned to.

  • default: person.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

FrontFacingCounterProcessor

Approximate attention based on whether the face for a given person is detected or not.

Parameters

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..
  • default: False.

HeadPoseProcessor

Calculate head pose (rotation respect to the camera) Sets the "head_pose" Rotation feature on the boxes. Sets the "_yaw_pitch_roll" feature on the boxes.

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: head.

• smooth_angles (bool): Smooth angles.

  • default: True.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Networks

• Network pose, defaults to FacePoseNetwork.

PersonAgeGenderProcessor

Find age and gender for the given face boxes

Parameters

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..
  • default: False.

Networks

• Network age_gender, defaults to FaceAgeGenderVoloNetwork.

ScreenAttentionProcessor

Calculate face attention as a percentage of total time looking to the camera surroundings. Requires that boxes have a "_head_pose" feature set (set by DirectMHPNetwork or similar).

Parameters

• head_pose_bias_auto (bool): Derive yaw bias automatically from the camera extrinsic tilt (calibration.json) instead of head_pose_bias_yaw_deg. Uses the empirical model in src/util/camera_bias.py..

  • default: True.

• head_pose_bias_pitch_deg (float): Additive pitch correction (degrees), applied before smoothing..

  • default: 0.0 (-45.0-45.0).

• head_pose_bias_roll_deg (float): Additive roll correction (degrees), applied before smoothing..

  • default: 0.0 (-45.0-45.0).

• head_pose_bias_yaw_deg (float): Additive yaw correction (degrees), applied before smoothing. 0 = no correction..

  • default: 0.0 (-45.0-45.0).

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: head.

• fallback_angle (float): Angle at which an unconfigured screen is considered to be being looked at.

  • default: 25.0 (0.0-180.0).

• gaze_cone_coverage_mode (str): 'footprint' = intersection/footprint_area (legacy). 'normalized' = intersection/min(footprint_area, screen_area). Normalized mode is equivalent to footprint at close range and screen-coverage at far range..

  • default: normalized.

• gaze_cone_half_angle_deg (float): Cone half-angle in degrees (cone mode only). Defaults to 8.0 to match DirectMHP yaw MAE. Larger = more tolerant; smaller = stricter..

  • default: 10.0 (0.5-45.0).

• gaze_cone_hit_ratio (float): Cone-footprint overlap threshold in [0, 1] (cone mode only). 0.30 = 30%% of the cone's footprint must land on the screen..

  • default: 0.2 (0.0-1.0).

• gaze_cone_n_samples (int): Number of cone-boundary samples used to form the footprint polygon (cone mode only). 32 balances accuracy vs speed..

  • default: 32 (8-128).

• gaze_debug_csv (bool): Enable per-box CSV logging of gaze-hit intermediate values (slows FPS; for benchmarking)..

  • default: False.

• gaze_hit_mode (ray|cone): Gaze hit-test mode. 'ray' = central-ray intersection (legacy). 'cone' = flashlight-cone footprint overlap test..

  • default: cone.

• gaze_margin (float): Multiplier on screen half-size used for gaze-hit tolerance (1.0 = exact screen edges)..

  • default: 1.5 (0.1-5.0).

• scene_bias_pitch_deg (float): Per-scene pitch correction (degrees), summed with the pitch from head_pose_bias_auto / head_pose_bias_pitch_deg. Default 0 = no overlay..

  • default: 0.0 (-45.0-45.0).

• scene_bias_yaw_deg (float): Per-scene yaw correction (degrees), summed with the yaw from head_pose_bias_auto / head_pose_bias_yaw_deg. Produced by tools/calibrate_scene_bias.py. Default 0 = no overlay..

  • default: 0.0 (-45.0-45.0).

• smooth_angles (bool): Enable circular-mean smoothing of yaw/pitch/roll before gaze evaluation..

  • default: False.

• smooth_angles_min_samples (int): Minimum samples in window before smoothing kicks in; below this, raw angle passes through..

  • default: 3 (1-60).

• smooth_angles_window_sec (float): Time window (seconds) for AngleSmoother. FPS-invariant: 0.2s covers ~5 frames @25fps..

  • default: 0.2 (0.0-5.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

SelectiveAgeGenderProcessor

Detect a single candidate age and gender, picking one per frame from the global stage in order of descending face box area.

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes to process.

  • default: face.

• keypoint_min_conf (float): Minimum per-keypoint confidence to trust a skeleton keypoint for body-orientation derivation..

  • default: 0.3.

• lock_pitch_deg (float): Additional lock condition on pitch: a PASS only locks the commit if |ema_pitch| is also below this. Prevents downward-looking misclassifications from anchoring the gender result. Set to 90 to disable..

  • default: 90.0.

• lock_quality_deg (float): Initial-lock threshold: an actor's first PASS only locks the commit if |ema_yaw| is below this. Earlier PASSes still commit features but don't lock — every subsequent PASS overwrites until a high-quality one arrives and locks. Set to a large value (e.g. 90) to lock on the very first PASS like before..

  • default: 30.0.

• log_raw_pose (bool): Log raw yaw/pitch/roll for every head candidate evaluated each frame. Diagnostic..

  • default: False.

• max_abs_pitch_deg (float): Skip candidate if |pitch| exceeds this (degrees). Only applied when _yaw_pitch_roll is present on the box..

  • default: 50.0.

• max_abs_yaw_deg (float): Skip candidate if |yaw| exceeds this (degrees). Only applied when _yaw_pitch_roll is present on the box..

  • default: 90.0.

• max_abs_yaw_deg_relaxed (float): Relaxed |yaw| gate that applies when the skeleton independently confirms a sideways body pose facing the camera. Falls back to PARAM_MAX_ABS_YAW when no usable skeleton is available..

  • default: 75.0.

• max_ttl (float): Maximum time to live for a box before it is discarded.

  • default: 10.0 (0.0-360.0).

• min_actor_frames (int): Minimum number of frames an actor must be evaluated before age/gender inference is attempted. Filters out ghost tracks that appear briefly. Set to 0 to disable (classify on first eligible frame)..

  • default: 0.

• min_face_size (int): Minimum face size in pixels to classify a face candidate. Set to 0 to disable..

  • default: 64.

• min_frontal_frames (int): Minimum consecutive frames the raw pose must stay within the frontal zone before a candidate is accepted. Resets to 0 whenever the pose gate fires..

  • default: 3.

• min_pose_score (float): Skip candidate if its DirectMHP _pose_score is below this threshold. Default matches DirectMHP's own internal filter; raise via INI to be more conservative..

  • default: 0.5.

• pose_max_jump_deg (float): Reject a raw yaw reading whose circular distance from the previous accepted raw yaw exceeds this. Guards against DirectMHP back-of-head sign flips. Set <=0 to disable..

  • default: 45.0.

• pose_max_consecutive_rejects (int): After this many consecutive velocity-gate rejections, accept the next reading regardless of jump magnitude. Prevents permanent freeze on legitimate fast head turns..

  • default: 5.

• pose_smooth_min_samples (int): Minimum samples before AngleSmoother's MAD outlier check kicks in. Bootstrap frames are accepted..

  • default: 3.

• pose_smooth_window (int): AngleSmoother window size (frames) used purely as a MAD-based outlier validator on raw yaw/pitch/roll per head box.id. The smoothed output is discarded; only the per-sample outlier verdict is consumed..

  • default: 7.

• quality_improve_deg (float): First-PASS-locks: once an actor has a committed age/gender, only overwrite if the new PASS has |ema_yaw| at least this many degrees lower (more frontal) than the locked-in PASS. Set to a large value (e.g. 200) to never overwrite; set to 0 to always overwrite..

  • default: 15.0.

• shoulder_ratio_sideways (float): |L_SHO.x - R_SHO.x| / head_w below which the body is considered sideways (shoulders project narrowly in image space)..

  • default: 0.5.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• use_body (bool): Use face and body picture with the network. Off by default: the current model (mivolo_v1_lagenda.onnx) does not use its body input at all — see devdocs/reports/agegender-mivolo-body-channel-dead.md. Kept (rather than removed) so a working dual-input checkpoint can be dropped in later without redoing this plumbing..

  • default: False.

Networks

• Network age_gender_network, defaults to FaceAgeGenderVoloNetwork.

SelectiveInferenceProcessor

Superclass for processors acting on the global stage. Override and implement a metric to define order of box processing. One box will be processed per frame.

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes to process.

  • default: face.

• max_ttl (float): Maximum time to live for a box before it is discarded.

  • default: 10.0 (0.0-360.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

SelectivePoseBasedAgeGenderProcessor

Detect a single candidate age and gender per frame, gating each head on the attached YOLO skeleton's keypoint confidences and geometry instead of a DirectMHP _yaw_pitch_roll reading.

The gate is a cheap, robust reject decision (not degree-accurate pose):

1. Visibility (hard): nose + BOTH eyes confident. Requiring both eyes removes looking-away and hard profiles at zero marginal cost.
2. Frontality: eye/ear symmetry asymmetry below max_asymmetry.
3. Resolution: inter-ocular pixel distance above min_interocular_px (in addition to the min_face_size box gate in metric(), which runs even earlier and silently excludes a candidate from ever reaching this gate at all).
4. Frontal hysteresis: stay inside the gate min_frontal_frames frames.
5. Best-frame commit-lock: classify once per track, locking on the frame with the lowest asymmetry (asymmetry replaces |yaw| from the DirectMHP-based SelectiveAgeGenderProcessor).

All frontality geometry lives on :meth:Skeleton.head_frontality.

Parameters

• allow_profile (bool): Also accept side/profile views (one eye + its same-side ear confidently visible -- see Skeleton.head_frontality) for classification, not just frontal faces. Off by default (opt-in; introduced alongside a coverage/accuracy benchmark -- see devdocs/reports). A profile PASS is always ranked worse than an accepted frontal one and never locks, so a later frontal read for the same track still wins if one appears..

  • default: False.

• allow_sideways_body (bool): When require_body_facing is on, don't veto a candidate whose shoulders project narrowly in image space (see shoulder_ratio_sideways) as 'facing away' -- a near-perpendicular shoulder line makes the l_sho.x/r_sho.x sign essentially noise, so treat it as a genuine side-on body pose instead of a confident back-turn. Off by default (opt-in, unvalidated at scale); pairs with allow_profile to admit real side-view candidates that require_body_facing otherwise blocks the same way as someone with their back to the camera. Ported from SelectiveAgeGenderProcessor's body_sideways signal..

  • default: False.

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes to process.

  • default: face.

• head_kpt_min_conf (float): Minimum per-keypoint confidence for nose/eye/ear landmarks to be trusted in the frontality gate (tier-1 visibility threshold). Raised from 0.4 after a 3kids/5guys threshold sweep confirmed 0.4 let low-confidence back-of-head keypoints pass as a spuriously symmetric "frontal" face; see devdocs/reports/agegender-independent-mot-accuracy-thisbranch-vs-develophead.md..

  • default: 0.6.

• keypoint_min_conf (float): Minimum per-keypoint confidence to trust a shoulder keypoint for the body-facing corroboration..

  • default: 0.3.

• lock_asymmetry (float): Initial-lock threshold: an actor's first PASS only locks the commit if its asymmetry is below this. Earlier PASSes still commit features but don't lock. Set to a large value (e.g. 1.0) to lock on the very first PASS..

  • default: 0.15 (0.0-1.0).

• log_gate (bool): Log the per-candidate gate decision each frame. Diagnostic..

  • default: False.

• max_asymmetry (float): Skip candidate if its eye/ear frontality asymmetry (0=frontal, 1=profile) exceeds this. The yaw proxy..

  • default: 0.25 (0.0-1.0).

• max_ttl (float): Maximum time to live for a box before it is discarded.

  • default: 10.0 (0.0-360.0).

• min_actor_frames (int): Minimum number of frames an actor must be evaluated before age/gender inference is attempted. Filters out ghost tracks that appear briefly. Set to 0 to disable..

  • default: 0.

• min_face_size (int): Minimum face size in pixels to classify a face candidate. Set to 0 to disable. Lowered from 64 to 30 -- at 64 this silently excluded candidates (no log tag, rejected in metric() before process_candidate ever runs); see the fvstore4 PID 6 investigation in devdocs/reports..

  • default: 30.

• min_frontal_frames (int): Minimum consecutive frames the pose must stay within the frontal gate before a candidate is accepted. Resets to 0 whenever the gate fires..

  • default: 3.

• min_interocular_px (int): Skip candidate if inter-ocular distance (px) is below this usable-resolution floor. 0 disables (rely on min_face_size)..

  • default: 15.

• quality_improve (float): First-PASS-locks: once an actor has a committed age/gender, only overwrite if the new PASS asymmetry is at least this much lower (more frontal) than the locked one. Set to 0 to always overwrite..

  • default: 0.03 (0.0-1.0).

• require_body_facing (bool): Reject a candidate when the skeleton shoulders confidently indicate the body faces AWAY from the camera (subject's left shoulder appears on the camera's left). The face keypoints can still fire on a turned/back head, so this kills back-of-head admits the frontality metric alone lets through. Skipped when no confident shoulder pair is available..

  • default: True.

• shoulder_ratio_sideways (float): |L_SHO.x - R_SHO.x| / box width below which the body is considered genuinely side-on rather than confidently facing away. Only consulted when allow_sideways_body is on. Matches SelectiveAgeGenderProcessor's shoulder_ratio_sideways default..

  • default: 0.5.

• strict_body_facing (bool): When require_body_facing is also on, reject unless the shoulders CONFIRM facing-camera (not just 'not confirmed facing away'). Closes the gap where no confident shoulder pair is available at all -- the exact situation the 3kids back-of-head false-frontal read slipped through in (see devdocs/reports/agegender-3kids-gender-accuracy-fixes.md). Off by default: this is a stricter, unvalidated-at-scale opt-in that trades coverage (candidates with occluded/out-of-frame shoulders get rejected too) for safety against this class of false positive..

  • default: False.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• use_body (bool): Use face and body picture with the network. Off by default: the current model (mivolo_v1_lagenda.onnx) does not use its body input at all — see devdocs/reports/agegender-mivolo-body-channel-dead.md. Kept (rather than removed) so a working dual-input checkpoint can be dropped in later without redoing this plumbing..

  • default: False.

• vote_commit (bool): Pool the first vote_max_samples PASS frames per actor and commit the frontality-weighted majority gender + weighted median age, instead of taking whichever single frame scored the best asymmetry. Best-frame commit lets one marginally more frontal frame overwrite a correct categorical label (observed M->F relocks on 5guys and gelateria2). Off by default..

  • default: False.

• vote_max_samples (int): Inference budget per actor when vote_commit is on. Each MiVOLO v2 call costs ~100ms-1s, so this is a hard cap: once spent the actor stops inferring entirely. Gender is already 100% on the benchmark set at 2; measured fps is flat up to 20 (the gate admits few enough frames that the budget rarely binds), so this is set for age, which is the metric that actually moves..

  • default: 3 (1-50).

Networks

• Network age_gender_network, defaults to FaceAgeGenderVoloNetwork.

Module filters

FeatureFilterProcessor

Filter the given feature using the given parameters.

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Box type to process features for.

  • default: combo.

• feature_id (str): Feature ID to filter.

  • default: _head_pose.

• filter_args (dict): Filter init arguments.

  • default: {}.

• filter_type (float|vector|angle|quaternion): Filter type to apply.

  • default: angle.

• max_age (float): Max age of a feature in seconds.

  • default: 60.0 (0.0-1000.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Module globalstage

ActorAgeGenderProcessor

Detect a single candidate age and gender, picking one per frame from the global stage in order of descending face box area.

Parameters

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• use_body (bool): Use face and body picture with the network. Off by default: the current model (mivolo_v1_lagenda.onnx) does not use its body input at all — see devdocs/reports/agegender-mivolo-body-channel-dead.md. Kept (rather than removed) so a working dual-input checkpoint can be dropped in later without redoing this plumbing..

  • default: False.

Networks

• Network age_gender_network, defaults to FaceAgeGenderVoloNetwork.

ActorInZoneProcessor

Track boxes hitting into/out of a certain contour

Parameters

• box_position (center|topcenter|bottomcenter): Position on the box to locate inside/outside the area.

  • default: bottomcenter.

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will use for the detection.

  • default: person.

• contour (polygon): Contour Polygon where to detect entrance.

  • default: [].

• contour_name (str): Name of the detection contour.

  • default: contour.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

ActorMultiZoneProcessor

Preserve current and previous zones of an actor. Needs "_gate_contour" feature to be set by GateProcessor. Sets actor.features["current_zone"] and actor.features["last_zone"]

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will use for the detection.

  • default: combo.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

StageLoaderProcessor

Load IDENTIFIED person and face boxes into actors

Parameters

• actor_box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of actor boxes to use as actor basis.

  • default: person.

• debug_boxes (bool): Generate debug boxes for annotation.

  • default: True.

• exit_time_interval (float): Time to wait to consider an actor out of stage.

  • default: 6.0 (0.0-600).

• ingress_time_interval (float): Time to wait to consider an actor in stage.

  • default: 3.0 (0.0-60).

• lost_time_interval (float): Time to wait to consider an actor lost.

  • default: 2.0 (0.0-60).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• track_face_boxes (bool): Add identified faces to actors.

  • default: True.

StageReadingProcessor

Superclass for processors acting on the global stage. Override and implement a metric to define order of box processing. One box will be processed per frame.

Parameters

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..
  • default: False.

StageReportProcessor

Report stage status and events like actor entrances exits.

Parameters

• debug_boxes (bool): Generate debug boxes for annotation.

  • default: True.

• enable_http (bool): Enable HTTP POSTing of stage to send_status_post_url.

  • default: False.

• enable_mqtt (bool): Enable MQTT sending to user-defined channel send_status_mqtt_channel.

  • default: False.

• is_view_time_interval (float): Minimum attention time to consider presence a view event.

  • default: 2.0 (0.0-60).

• send_status_mqtt_channel (str): Use this MQTT channel instead of the default one for status messages.

  • default: /vision.

• send_status_post_url (str): Send a HTTP POST (JSON) request with the whole stage info every send_status_time_interval..

  • default: http://localhost:8085.

• send_status_time_interval (float): Send a MQTT status packet with the whole stage info every time interval. Zero disables..

  • default: 1.0 (0.0-60.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Module image

ImageCircleCropProcessor

Clip an image region and black out outside. Useful as a preprocessing step to blank outside interferences.

Parameters

• dx (int): Pixels of center x offset.

  • default: 0 (-10000-10000).

• dy (int): Pixels of center x offset.

  • default: 0 (-10000-10000).

• radius (int): Radius of the circle.

  • default: 300.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• plane (rgb|z): Color plane to use.

  • default: z.

ImageRegionProcessor

Clip an image region and black out outside. Useful as a preprocessing step to blank outside interferences.

Parameters

• contour (polygon): Polygon area of the image to clip.

  • default: [].

• crop (bool): Crop the boundaries of the contour.

  • default: True.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

ZDepthFilterProcessor

Mask the RGB image of the snapshot using the Z (depth) image, clipping between two intervals.

Parameters

• threshold_max (float): Maximum distance threshold.

  • default: 3000 (0-4294967296).

• threshold_min (float): Minumum distance threshold.

  • default: 1000 (0-4294967296).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Module tag

AreaEnterExitProcessor

Track boxes entering/exiting a given area limiting boundary.

Parameters

• area_name (str): Name of the area.

  • default: Area1.

• box_position (center|topcenter|bottomcenter): Position on the box to locate inside/outside the area.

  • default: center.

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will use for the detection.

  • default: head.

• report_post_period (float): Period of POST updates, in seconds.

  • default: 30.0 (0.0-1000.0).

• report_post_url (str): URL where to POST counter updates.

  • default: None.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

AreaHitProcessor

Track tracked boxes hitting into/out of a certain contour/gate

Parameters

• bounce_band (int): Bounce band width where no count is made.

  • default: 28.

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: combo.

• counter_type (contour|gate): Type of counter to use.

  • default: gate.

• distance_threshold (int): Distance threshold to consider a box as entering/exiting.

  • default: 70.

• enable_events (bool): Enable events to be sent to the MQTT broker.

  • default: True.

• contact_point (center|top_middle|bottom_middle|head|feet): Point to check for presence inside/outside the contour.

  • default: feet.

• hysteresis_frames (int): Number of frames to wait before counting a double crossing.

  • default: 8.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

AreaTaggerProcessor

Add a tag to any boxes whose center point (or top center or bottom center) enter the area of interest.

Parameters

• area (polygon): Detection area for tag.

  • default: None.

• box_position (center|topcenter|bottomcenter): Position on the box to locate inside/outside the area.

  • default: bottomcenter.

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: face.

• tag (str): Tag to mark on area hit.

  • default: tag1.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

DoorCounterProcessor

Track boxes passing a door and inside a given contour.

Parameters

• area_limit (int): Maximum number of persons this area allows.

  • default: 10.

• area_name (str): Name of the area this door enters or exits.

  • default: area1.

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: person.

• door (polygon): Polygon representing the entry door.

  • default: [[0, 240], [640, 240]].

• door_name (str): Name of the door.

  • default: door1.

• inside (square): Square to mark the inside area (centroid will be used).

  • default: [[320, 400], [330, 400], [330, 410], [320, 410]].

• remove_timeout (float): Timeout (seconds) for stale boxes to be removed.

  • default: 10.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• track_bottom (bool): Count crossings at the feet, instead of the center of the person box.

  • default: True.

GateProcessor

Tracks entrances and exits of gates and zones. Allows to send events when a box enters/exits a gate or zone.

Parameters

• bounce_band (int): Bounce band width where no count is made.

  • default: 28.

• bounce_band_cm (float): bounce_band in real-world centimetres, converted to pixels local to the gate via the camera calibration. None (default) keeps the pixel constant (bounce_band) unconditionally; requires a calibrated camera to take effect..

  • default: None.

• box_target (center|top_middle|bottom_middle|head|feet): Target point of the box to track.

  • default: feet.

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo|any): Type of boxes this processor will filter.

  • default: combo.

• confirm_max_duration_s (float): A candidate open longer than this without confirming is discarded as inconclusive. A safety valve, not the typical confirmation latency -- a real slow crossing can legitimately take tens of seconds to clear the bounce band (e.g. someone browsing near a zone boundary)..

  • default: 45.0 (0.1-120.0).

• confirm_min_frames (int): Minimum reliable, new-side samples a crossing candidate needs before it can confirm (fire)..

  • default: 2 (1-50).

• counter_type (contour|gate): Type of counter to use.

  • default: gate.

• csv_log (bool): Log crossing events to a CSV file for diagnostics.

  • default: False.

• debug_feet_stages (bool): Store post-Gate-EMA point for debug visualization.

  • default: False.

• diag_csv (bool): Write per-frame diagnostic CSV for contour crossing analysis.

  • default: False.

• distance_threshold (int): Distance threshold to consider a box as entering/exiting.

  • default: 70.

• distance_threshold_cm (float): distance_threshold in real-world centimetres, converted to pixels local to the gate via the camera calibration. None (default) keeps the pixel constant (distance_threshold) unconditionally; requires a calibrated camera to take effect..

  • default: None.

• enable_events (bool): Enable events to be sent to the MQTT broker.

  • default: True.

• head_vel_ema (float): EMA alpha for head velocity smoothing.

  • default: 0.4.

• hysteresis_frames (int): Number of frames to wait before counting a double crossing.

  • default: 8.

• idswap_speed_mps (float): Min world-space feetpoint speed (m/s) implied between a crossing candidate's first and most recent sample for it to be rejected as an ID-swap teleport rather than a genuine crossing. Walking is ~1.5, running ~6; teleports are hundreds..

  • default: 8.0 (0.0-1000.0).

• min_reliable_confidence (float): Minimum Phase 3 reliability (SmoothFeetProcessor) for a sample to count as confirming evidence -- a source-switch frame reads low and is excluded, not voted against the crossing..

  • default: 0.5 (0.0-1.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

TryOnProcessor

Virtual Try-On Processor Sets up a table contour for pick and place actions

Parameters

• bistate_frames (int): Number of frames of delay for pick/place trigger.

  • default: 10.

• box_try_on_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of box where the pickables should be inside-of to be considered a try-on.

  • default: face.

• pickables (str): Comma separated list of pickable classes.

  • default: glasses1,glasses2,glasses3.

• table_contour (polygon): Polygon of the pick/place table.

  • default: [[0.0, 0.5], [1.0, 0.5], [1.0, 1.0], [0.0, 1.0]].

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• use_global_stage (bool): Use boxes from the global stage.

  • default: True.

Module tracking

AreaKalmanTrackingProcessor

Kalman based box tracking with delimited areas of tracking and areas where no trackers are expected to be "born" (e.g. you don't expect someone to appear from nowhere in the middle of the frame).

Parameters

• association_iou (float): Minimum IOU overlap percent for a track to match a tracker.

  • default: 0.3 (0.0-1.0).

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: person.

• max_age (int): Maximum age in FRAMES for a tracklet to survive.

  • default: 50 (0-9999).

• min_hits (int): Minimum number of hits for a tracklet to survive.

  • default: 3 (0-1000).

• no_birth_area (polygon): Area of the image where no trackers should appear.

  • default: [].

• re_association_distance (float): Re-association distance to re-match an unmatched detection.

  • default: 50 (0.0-200).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• tracking_area (polygon): Area of the image where to track.

  • default: [].

BoxOverlapIdentifierProcessor

Assigns and recognizes box ids based on simple IOU overlap

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: person.

• discard_older_than (float): Discard seen boxes when more than (secs) have passed.

  • default: 3 (0-9999).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• update_iou (float): Minumum IOU between frames to preserve stable coordinates.

  • default: 0.8 (0.0-1.0).

FaceInsidePersonIdentifierProcessor

Assigns and recognizes faces inside person boxes and matches their IDs if possible.

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes for the person container (person, topbody, etc).

  • default: person.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

KalmanTrackingProcessor

Basic Kalman-based Tracking Processor

Parameters

• association_iou (float): Minimum IOU overlap percent for a track to match a tracker.

  • default: 0.3 (0.0-1.0).

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: person.

• max_age (float): Maximum age in FRAMES for a tracklet to survive.

  • default: 3.0 (0-999).

• min_hits (int): Minimum number of hits for a tracklet to survive.

  • default: 3 (0-1000).

• re_association_distance (float): Re-association distance to re-match an unmatched detection.

  • default: 50 (0.0-20000).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

ReidentifierProcessor

DNN-embedding based reidentification processor @deprecated

Parameters

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..
  • default: False.

SmoothFeetProcessor

Extract feet position from combo boxes and smooth it.

Parameters

• anchor_ky (float): Vertical anchor offset into head bbox (fraction of h_px).

  • default: 0.2 (0.0-0.5).

• ankle_ema_tolerance_m (float): Max |ankle_height - EMA| (m) to accept ankle-height HEIGHT COMMIT. Additive to the basic plausibility range check. Does NOT gate or delay runtime ankle midpoint feetpoint usage..

  • default: 0.3 (0.05-1.0).

• ankle_floor_offset_m (float): Ankle-to-floor offset in meters (ankles are above ground).

  • default: 0.08 (0.0-0.2).

• ankle_geometry_check_enable (bool): Reject ankle keypoints that fail anatomical sanity (ankle below knee below hip). Defends against pose-net hallucination on occluded ankles..

  • default: True.

• ankle_height_enable (bool): Enable one-shot ankle-based height capture when both ankles visible.

  • default: True.

• ankle_height_max_m (float): Maximum plausible person height (m) for ankle capture.

  • default: 2.2 (1.5-2.5).

• ankle_height_min_m (float): Minimum plausible person height (m) for ankle capture.

  • default: 1.0 (0.5-1.5).

• ankle_midpoint_enable (bool): Use ankle midpoint as highest-priority runtime feetpoint source when reliable.

  • default: True.

• ankle_midpoint_min_conf (float): Minimum per-ankle keypoint confidence for ankle midpoint runtime source.

  • default: 0.5 (0.1-1.0).

• bbox_filter (bool): Enable EMA filtering of head bbox before projection.

  • default: True.

• bestk (bool): Enable best-K sample aggregation for freeze.

  • default: False.

• bestk_k (int): Number of top-quality samples to keep.

  • default: 10 (3-50).

• bestk_min_gap (int): Min frame gap between kept samples (diversity constraint).

  • default: 3 (1-50).

• bestk_min_span (int): Min frame span between first and last top-K sample to allow freeze.

  • default: 30 (5-500).

• bypass_delta_thresh (float): Min screen-space feetpoint jump (px) to trigger source-switch bypass. 0=always bypass.

  • default: 30.0 (0.0-200.0).

• csv_log (bool): Enable CSV debug logging of feet metrics (slows FPS).

  • default: False.

• debug_feet_stages (bool): Store pre-smooth feetpoint for debug visualization.

  • default: False.

• elliptical_width (bool): Use elliptical yaw-aware width model.

  • default: False.

• feet_smooth_adaptive (bool): Use adaptive alpha based on innovation magnitude.

  • default: False.

• feet_smooth_alpha (float): EMA alpha for world-XY feetpoint smoothing (0=OFF, 1=no smoothing).

  • default: 0.18 (0.0-1.0).

• feet_smooth_alpha_max (float): Adaptive: max alpha (light smoothing for large moves).

  • default: 0.5 (0.01-1.0).

• feet_smooth_alpha_min (float): Adaptive: min alpha (heavy smoothing for small moves).

  • default: 0.08 (0.01-1.0).

• feet_smooth_innov_thresh (float): Adaptive: innovation threshold (m) for alpha ramp.

  • default: 0.15 (0.01-1.0).

• freeze_tolerance (float): Freeze variance tolerance as fraction of ref height 1.70m (e.g. 0.10 = 10%).

  • default: 0.05 (0.01-0.3).

• geo_alpha_floor (float): Minimum geo weight floor (lambda) for soft gate alpha scaling.

  • default: 0.0 (0.0-1.0).

• geo_cy_max (float): Max normalized cy (head_cy/img_h) for learning.

  • default: 0.85 (0.0-1.0).

• geo_gate (bool): Enable geometric sample gating for learning (depth + cy).

  • default: False.

• geo_max_depth (float): Max depth (m) for learning samples.

  • default: 15.0 (0.5-50.0).

• geo_soft (bool): Use soft geometric weight instead of hard reject.

  • default: False.

• head_d (float): Head depth front-to-back (m).

  • default: 0.195 (0.12-0.28).

• head_h (float): Head height top-to-chin (m).

  • default: 0.23 (0.15-0.3).

• head_w (float): Head width ear-to-ear (m).

  • default: 0.155 (0.1-0.25).

• h_px_gamma (float): Gamma exponent for H_proj shrinkage curve.

  • default: 0 (0-2.0).

• h_px_ref (float): Reference h_px for distance-aware H_proj shrinkage (0=disabled).

  • default: 0 (0-500).

• h_px_shrink_floor (float): Minimum shrinkage floor (prevents over-correction).

  • default: 0.85 (0.5-1.0).

• max_samples (int): Maximum number of samples to use for feet estimation.

  • default: 15 (0-100).

• min_distance (float): Minimum distance to the camera to consider for feet estimation.

  • default: 10.0 (0-100).

• postfreeze_max_height_jump (float): Max allowed height change (m) when replacing frozen height.

  • default: 0.15 (0.01-0.5).

• postfreeze_quality_margin (float): Min quality score improvement to replace frozen height.

  • default: 0.05 (0.0-0.5).

• postfreeze_refine (bool): Enable post-freeze height refinement (best-accepted-measurement policy).

  • default: False.

• projection_mode (str): Projection mode: hinted, pinhole, hinted_anchor.

  • default: hinted_anchor.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• uncal_head_multiplier (float): Head-heights below head bottom to estimate feet when uncalibrated and no ankles visible.

  • default: 6.0 (1.0-12.0).

• use_model_head_height (bool): Prefer the detector's per-model head height hint (_model_head_height box feature) over head_h when present.

  • default: True.

• yaw_blend (bool): Enable yaw-aware width/height fusion downweighting.

  • default: False.

• yaw_blend_scale (float): Yaw scale for width trust rolloff (higher=faster).

  • default: 1.0 (0.5-3.0).

TaggedDoorCounterProcessor

Track boxes hitting into/out of a certain contour

Parameters

• area_name (str): Name of the area this door enters or exits.

  • default: area1.

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: person.

• remove_timeout (float): Timeout (seconds) for stale boxes to be removed.

  • default: 15.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

TrackingProcessor

Tracking processor with configurable tracker.

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: person.

• coast_frames (int): Frames to keep emitting a predicted (coasted) PLACEHOLDER box for a recently-confirmed track that the tracker stopped returning, so the Stage actor is not retired during a short occlusion gap (0=disabled). Keep <= the tracker's lost window (max_time_lost = fps/30*track_buffer) to avoid double-counting if the subject reappears under a new id..

  • default: 0 (0-100).

• debug_boxes (bool): Generate debug boxes for annotation.

  • default: True.

• default_tracker (basic|ucmc|botsort|bytetrack|ocsort|neotracker|headtracker): Default tracker to use.

  • default: ucmc.

• fallback_tracker (basic|ucmc|botsort|bytetrack|ocsort|neotracker|headtracker): Fallback tracker to use if default tracker cannot be used.

  • default: basic.

• fallback_tracker_params (dict): Extra fallback tracker parameters, passed to constructor.

  • default: {}.

• max_age (float): Maximum life in seconds for a lost tracklet to be removed.

  • default: 5.0 (1.0-20.0).

• preserve_skeletons (bool): Whether or not to preserve skeleton frames.

  • default: False.

• suppress_untracked (bool): Drop boxes whose tracked sub-box was not returned (confirmed) by the tracker, so unconfirmed/lost tracks do not leak downstream carrying an unstable id.

  • default: False.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

• tracker_params (dict): Extra tracker parameters, passed to constructor.

  • default: {}.

Networks

• Network reid_embedder, defaults to ReidentificationNetwork.

Module transform

SkeletonToUpperBodyBoxProcessor

Processor that converts skeleton keypoints to upper body bounding boxes.

Parameters

• replace_skeletons (bool): Replace skeletons with upper body boxes.

  • default: False.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

Module retired (deprecated)

APIReportingProcessor

Generate HTTP(s) calls on box enter/exit states. @deprecated

Parameters

• api_url (string): Reporting API endpoint.

  • default: http://api.end.pt.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

GridBasedCalibrationProcessor

@deprecated Grid based calibration for Broox Media Player tactile detection. Deprecated product. Do not use.

Parameters

• calibration (showcam|grid|bypass|calibrated): Fire calibration manually.

  • default: bypass.

• max_frame_count (int): Number of frames for calibration.

  • default: 300 (1-10000).

• stream_outfile (string): Full path of the wall.jpg file.

  • default: /tmp/wall.jpg.

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

LightTrackingProcessor

@deprecated: Used to control an array of lights to react to people passing.

Parameters

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..
  • default: False.

MappingProcessor

@deprecated Processor that maps coordinates over a 0-1 line over the defined contour

Parameters

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..
  • default: False.

PersonFaceStageProcessor

@deprecated Keep track of ingressing person and face boxes in a virtual "stage", setting its box.state (entering, entered, exiting, exited...) Specialized version of StageProcessor

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: face.

• exit_time_interval (float): Time to wait to consider a box out of stage.

  • default: 3.0 (0.0-60).

• ingress_time_interval (float): Time to wait to consider a box in stage.

  • default: 1.0 (0.0-60).

• is_view_time_interval (float): Minimum attention time to consider presence a view event.

  • default: 2.0 (0.0-60).

• send_status_post_url (str): Send a HTTP POST (JSON) request with the whole stage info every send_status_time_interval..

  • default: None.

• send_status_time_interval (float): Send a MQTT status packet with the whole stage info every time interval. Zero disables..

  • default: 1.0 (0.0-60.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.

StageProcessor

@deprecated Keep track of ingressing boxes in a virtual "stage", setting its box.state (entering, entered, exiting, exited...)

Parameters

• box_type (face|person|upper_body|blob|hand|head|skeleton|placeholder|combo): Type of boxes this processor will handle.

  • default: face.

• exit_time_interval (float): Time to wait to consider a box out of stage.

  • default: 3.0 (0.0-60).

• ingress_time_interval (float): Time to wait to consider a box in stage.

  • default: 1.0 (0.0-60).

• is_view_time_interval (float): Minimum attention time to consider presence a view event.

  • default: 2.0 (0.0-60).

• send_status_post_url (str): Send a HTTP POST (JSON) request with the whole stage info every send_status_time_interval..

  • default: None.

• send_status_time_interval (float): Send a MQTT status packet with the whole stage info every time interval. Zero disables..

  • default: 1.0 (0.0-60.0).

• trace (bool): Emit per-frame trace records for this processor when ProcessorTracer is enabled globally..

  • default: False.