Predict

Predicts keypoints on videos or images.

Video predictions are saved to:

<model_dir>/
└── video_preds/
    ├── <video_filename>.csv              (predictions)
    ├── <video_filename>_<metric>.csv     (losses)
    └── labeled_videos/
        └── <video_filename>_labeled.mp4

Image predictions are saved to:

<model_dir>/
└── image_preds/
    └── <image_dirname | csv_filename | timestamp>/
        ├── predictions.csv
        ├── predictions_<metric>.csv      (losses)
        └── <image_filename>_labeled.png


usage: litpose predict <model_dir> <input_path:video|image|dir|csv>...  [OPTIONS]

Positional Arguments

model_dir

path to a model directory

input_path

one or more video files, image files, CSV files, or directories to run prediction on

  • directories: iterates over videos or images in the directory

  • CSV file: must be formatted as a label file. predicts on the frames and computes

    pixel error against keypoint labels

Named Arguments

--overrides

overrides attributes of the config file. Uses hydra syntax: https://hydra.cc/docs/advanced/override_grammar/basic/

--precision

Possible choices: bf16, fp16, fp32

precision to run inference at. Does not affect the checkpoint on disk – weights stay fp32; this only controls precision during the forward pass. Default: fp32.

Default: 'fp32'

--overwrite

overwrite videos that already have prediction files

Default: False

--batch_size

override the batch size used during inference. For video inputs, sets dali.base.predict.sequence_length (or dali.context.predict.sequence_length for context models) – the number of frames DALI loads per batch. For CSV/image inputs, sets training.val_batch_size. Lower this if inference runs out of GPU memory; raise it to speed up inference on a GPU with memory to spare. Equivalent to passing the corresponding –overrides KEY=VALUE by hand.

--bbox_dir

directory containing bbox CSV files produced by litpose create_bbox or a compatible external source. For CSV inputs, looks for bbox.csv inside this directory. For video inputs, looks for <video_stem>_bbox.csv inside this directory. When provided, each frame is cropped to its bounding box before being passed to the model, and predictions are saved in the original coordinate space.

--runtime

Possible choices: eager, onnx, tensorrt

inference backend. ‘eager’ (default) runs the trained checkpoint. ‘onnx’ and ‘tensorrt’ run a session previously built with litpose export –runtime onnx / –runtime tensorrt. With –runtime onnx or –runtime tensorrt, –precision is ignored – the exported file’s own precision is what runs.

Default: 'eager'

--onnx-precision

Possible choices: fp16, fp32

which ONNX export to load (or, for –runtime tensorrt, which engine cache). Only used with –runtime onnx or –runtime tensorrt. If omitted and exactly one export exists, it is used automatically; if several exist, pass this to disambiguate.

--reader

Possible choices: dali, opencv, pynvvc

video-reading backend for video inputs. ‘dali’, ‘pynvvc’, or ‘opencv’. If omitted (default), auto-selects ‘pynvvc’ when it’s usable on this machine for the given video, else ‘dali’ when it’s installed, else ‘opencv’ (the portable fallback, always available). Independent of –runtime/–compile – this only controls video ingestion, not model execution. Ignored for CSV/image inputs.

--compile

compile the model with torch.compile() for faster inference. The first prediction after compiling is slower due to compilation overhead.

Default: False

post-prediction

--skip_viz

skip generating prediction-annotated images/videos

Default: False