nicetoolbox.detectors.feature_detectors.kinematics.velocity_body.VelocityBody

class nicetoolbox.detectors.feature_detectors.kinematics.velocity_body.VelocityBody(io, data, sequence_context, algorithm_instance: str)

Bases: BaseFeature

The VelocityBody class is a feature detector that computes the kinematics component.

The VelocityBody feature detector accepts the human_pose component (body_joints) as its primary input, which is computed using the human_pose method detector. The kinematics component of this feature detector calculates the Euclidean distance between adjacent frames, essentially determining the velocity of body movement from one frame to the next.

Initialize base detector with references.

Subclasses should call super().__init__() and set inference_config.

Methods

compute	Computes the kinematics component.
compute_output_folders	Compute extra output folders for all components.
compute_result_folders	Compute result folders for all components.
compute_viz_folders	Compute visualization folders for all components.
get_input_file	Get the input file path for a specific upstream detector.
run	Execute feature detector: compute() + post_compute().
visualization	Creates visualizations for the computed kinematics component.

Attributes

algorithm_type
components
predictions_mapping	Access predictions mapping from runtime config.
requires_out_folder
data
io
sequence_context
detector_config
algorithm_instance
inference_config
visualize

compute()

Computes the kinematics component.

This method calculates the Euclidean distance between adjacent frames for each keypoint. It handles both 2D and 3D data. The method starts by loading the joint data from the input files. It then computes the differences between adjacent frames for each keypoint. A zero-filled frame is added at the beginning to match the original number of frames. Finally, the Euclidean distance for each keypoint between adjacent frames is computed. The computed differences are stored in a dictionary and saved to a compressed .npz file with the following structure:

• displacement_vector_body_2d: A numpy array containing the computed differences

  for 2D data.

• velocity_body_2d: A numpy array containing the computed velocity for 2D data.

• displacement_vector_body_3d: A numpy array containing the computed differences

  for 3D data.

• velocity_body_3d: A numpy array containing the computed velocity for 3D data.

• data_description: A dictionary containing the data description for all of the

  above output numpy arrays. See the documentation of the output for more details.

Returns:

A dictionary containing the above mentioned parts of the

kinematics component.

Return type:

out_dict (dict)

compute_output_folders(requires_out_folder: bool) → Dict[str, str]

Compute extra output folders for all components.

compute_result_folders() → Dict[str, str]

Compute result folders for all components.

compute_viz_folders(visualize: bool) → Dict[str, str]

Compute visualization folders for all components.

get_input_file(component: str, algorithm: str) → Path

Get the input file path for a specific upstream detector.

Parameters:

• component – Component name (e.g., ‘body_joints’)

• algorithm – Algorithm name (e.g., ‘hrnetw48’)

Returns:

Path to the .npz result file

property predictions_mapping

Access predictions mapping from runtime config.

run() → Any

Execute feature detector: compute() + post_compute().

Returns computed data for visualization.

visualization(out_dict)

Creates visualizations for the computed kinematics component.

This method generates visualizations for the computed kinematics component. It checks if the output dictionary contains the keys ‘velocity_body_2d’ and ‘velocity_body_3d’. If these keys are present, their corresponding values are used to create the visualizations.

The method calculates the sum of movement per body part using the post_compute method. It then determines the global minimum and maximum values to define the y-limits of the graphs. Finally, it calls the visualize_mean_of_motion_magnitude_by_bodypart function from the kinematics_utils module to generate the visualizations.

Parameters:

out_dict (dict) – The output dictionary containing the computed kinematics component. It should contain the keys ‘velocity_body_2d’ and/or ‘velocity_body_3d’.