Command line interfaces

Attention

Many of the parameters of the command line interfaces are simply passed to OpenCV’s ArUco library. For more information on these parameters, please refer to the ArUco documentation.

NAPS – Hybrid tracking using SLEAP and ArUco tags

usage: naps-track [-h] --slp-path SLP_PATH [--h5-path H5_PATH] --video-path
                  VIDEO_PATH [--tag-node-name TAG_NODE_NAME] --start-frame
                  START_FRAME --end-frame END_FRAME --aruco-marker-set
                  ARUCO_MARKER_SET
                  [--half-rolling-window-size HALF_ROLLING_WINDOW_SIZE]
                  [--output-path OUTPUT_PATH]
                  [--aruco-crop-size ARUCO_CROP_SIZE]
                  [--aruco-adaptive-thresh-win-size-min ADAPTIVETHRESHWINSIZEMIN]
                  [--aruco-adaptive-thresh-win-size-max ADAPTIVETHRESHWINSIZEMAX]
                  [--aruco-adaptive-thresh-win-size-step ADAPTIVETHRESHWINSIZESTEP]
                  [--aruco-adaptive-thresh-constant ADAPTIVETHRESHCONSTANT]
                  [--aruco-perspective-rm-ignored-margin PERSPECTIVEREMOVEIGNOREDMARGINPERCELL]
                  [--aruco-error-correction-rate ERRORCORRECTIONRATE]

Named Arguments

--slp-path

The filepath of the SLEAP (.slp or .h5) file to pull coordinates from. This should correspond with the input video file. The SLEAP file contains pose estimation data required for NAPS.

--h5-path

The filepath of the analysis h5 file to pull coordinates from. This should correspond with the input video file and slp file. Because NAPS relies on having data in the format given by SLEAP analysis h5s, you can skip a step by providing the analysis h5 file directly. If this is not provided, NAPS will pull the data from the SLEAP file.

--video-path

The filepath of the video used with SLEAP. This should be the video file that SLEAP was run on.

--tag-node-name

The ArUco tag SLEAP node name. This should correspond to the node name of the ArUco tag in the SLEAP data. ‘tag’ is set as the default value.

Default: “tag”

--start-frame

The zero-based fully-closed frame to begin NAPS assignment. This value allows you to specify from which frame to start the processing.

--end-frame

The zero-based fully-closed frame to stop NAPS assignment. This allows you to specify at which frame to end the processing.

--aruco-marker-set

The ArUco markers used in the video. This must match the specific set of ArUco markers used in the video for accurate detection and tracking. An example would be DICT_5X5_50, which is a set of 50 5x5 markers. More information can be found in the OpenCV documentation.

--half-rolling-window-size

Specifies the number of flanking frames (prior and subsequent) required in the rolling window for Hungarian matching a frame. The larger this window, the more frames will be used for matching. This can result in more robust tracks but in the event of an identity swap, it may take longer to correct the identity. The default is set to 5, resulting in an 11 frame window. You should change this depending on your intended use and your recording setup.

Default: 5

--output-path

Output path of the resulting SLEAP h5 analysis file. The default value is ‘naps_output.analysis.h5’, storing the output in the current working directory. If a different location or file name is preferred, it can be specified here.

Default: “naps_output.analysis.h5”

--aruco-crop-size

The number of pixels horizontally and vertically around the ArUco SLEAP node to identify the marker. The cropping area should be large enough to include the whole marker for accurate detection, but not much larger, to keep the processing efficient and avoid capturing multiple tags. This is data set specific.

--aruco-adaptive-thresh-win-size-min

Specifies the value for adaptiveThreshWinSizeMin used in adaptive thresholding. This parameter affects the adaptive thresholding in the ArUco marker detection, which can impact the robustness of marker detection. The default value is 10, a commonly used value. More information can be found in the OpenCV documentation.

Default: 10

--aruco-adaptive-thresh-win-size-max

Specifies the value for adaptiveThreshWinSizeMax used in adaptive thresholding. This parameter, similar to adaptiveThreshWinSizeMin, influences the adaptive thresholding. The default value is 30, providing a larger window size for the thresholding process, improving marker detection under diverse lighting conditions. More information can be found in the OpenCV documentation.

Default: 30

--aruco-adaptive-thresh-win-size-step

Specifies the value for adaptiveThreshWinSizeStep used in adaptive thresholding. This parameter determines the step size for the window in adaptive thresholding, affecting the granularity of the process. The default value is 12, offering a balanced choice between processing speed and thresholding precision. More information can be found in the OpenCV documentation.

Default: 12

--aruco-adaptive-thresh-constant

Specifies the value for adaptiveThreshConstant used in adaptive thresholding. This parameter is a constant subtracted from the mean or weighted sum of the neighbourhood pixels. The default value is 3, which works well in most scenarios, but can be adjusted based on specific lighting conditions. More information can be found in the OpenCV documentation.

Default: 3

--aruco-perspective-rm-ignored-margin

Specifies the value for perspectiveRemoveIgnoredMarginPerCell. This parameter is used in the perspective removal of the marker. The default value is 0.1, which is a reasonable value for many situations. More information can be found in the OpenCV documentation.

Default: 0.1

--aruco-error-correction-rate

Specifies the value for errorCorrectionRate. This parameter is used for error correction when decoding ArUco tags. The default value is 1 is to fully utilize the error capability for each tag dictionary. Adjust this parameter can be necessary for improving the robustness of marker detection, especially in the presence of camera noise or occlusions. More information can be found in the OpenCV documentation.

Default: 1