agents.components.motion_detection#

Module Contents#

Classes#

MotionDetector

This component detects motion (i.e. scene dynamics) from a stream of images or a stream of point clouds.

API#

class agents.components.motion_detection.MotionDetector(*, inputs: List[agents.ros.Topic], outputs: Optional[List[agents.ros.Topic]] = None, config: Optional[agents.config.MotionDetectorConfig] = None, trigger: Union[agents.ros.Topic, List[agents.ros.Topic]], position: Optional[agents.ros.Topic] = None, component_name: str, **kwargs)#

Bases: agents.components.component_base.Component

This component detects motion (i.e. scene dynamics) from a stream of images or a stream of point clouds.

A component instance takes either Image/CompressedImage input topics or PointCloud2 input topics (never both at once), and its available outputs depend on the input modality:

  • Bool output (both modalities): published motion state, True while motion is being detected. This output plugs directly into the EMOS event system, e.g. to trigger an MLLM component when something moves.

  • Video output (image inputs only): consecutive frames with perceivable motion are collected and published as a single video message once the motion stops (with a configurable debounce), i.e. the component makes intentionality decisions about what sequence of consecutive images should be treated as one coherent temporal sequence.

  • PoseArray output (point cloud inputs only): centers of the regions in which motion is being detected, published while motion is active. Multiple simultaneously moving regions produce multiple centers.

Point cloud motion is detected by sparse voxel-occupancy differencing against an accumulated history. Each cloud is voxelized and compared with the union of the last accumulation_window clouds; newly appearing voxels are clustered, and only voxels belonging to spatially coherent clusters (of at least min_cluster_size) count as motion evidence, which is thresholded for the motion state and whose clusters become the motion centers. Differencing against an occupancy history makes detection robust to sparse and non-repetitive scan patterns (e.g. Livox lidars), while the coherence requirement filters out scattered appearances from sensor noise or people standing quasi-still. Detection starts once the history window is full. Note that sustained motion slower than roughly one voxel edge per window duration will blend into the history and can go undetected; lower voxel_size or raise accumulation_window to detect slower motion.

An optional position (Odometry) topic enables use on a moving robot:

  • With point cloud inputs, each cloud is transformed into the odometry frame before differencing (planar ego-motion subtraction), so static world geometry cancels out and motion centers are published in the odometry frame. If the transform betweeen cloud and robot base frame is not available, the cloud is assumed to be given in the robot base frame. Without a position topic, the sensor is assumed static and centers are published in the cloud frame.

  • With image inputs, motion detection is suppressed while the robot is moving faster than a configurable speed threshold.

Parameters:

  • inputs (list[Topic]) – The input topics for motion detection. This should be a list of Topic objects of Image, CompressedImage or PointCloud2 type (one modality per component).

  • outputs (list[Topic]) – The output topics for the detected motion. This should be a list of Topic objects of Bool, Video (image inputs) or PoseArray (point cloud inputs) type.

  • config (MotionDetectorConfig) – The configuration for the motion detection. This should be an instance of MotionDetectorConfig. If not provided, defaults are used.

  • trigger (Union[Topic, list[Topic]]) – The trigger topic(s) for the component. Input messages on these topics drive the processing. This can be a single Topic object or a list of Topic objects.

  • position (Optional[Topic]) – Optional robot odometry topic used for ego-motion handling (see above). An Odometry topic given directly in inputs is treated the same way.

  • component_name (str) – The name of the motion detection component. This should be a string.

Example usage:

image_topic = Topic(name="image", msg_type="Image")
video_topic = Topic(name="video", msg_type="Video")
motion_topic = Topic(name="motion", msg_type="Bool")
config = MotionDetectorConfig(motion_estimation_func="frame_difference")
motion_detector = MotionDetector(
    inputs=[image_topic],
    outputs=[video_topic, motion_topic],
    config=config,
    trigger=image_topic,
    component_name="motion_detector",
)
custom_on_configure()#

Configure.

custom_on_activate()#

Custom configuration for creating triggers.

create_all_subscribers()#

Override to handle trigger topics and fixed inputs. Called by parent BaseComponent

activate_all_triggers() → None#

Activates component triggers by attaching execution step to callbacks

destroy_all_subscribers() → None#

Destroys all node subscribers