Practical overview
When it fits
Use it when you need a code-based pose-estimation example or a starting point for custom training, and can work with the listed older TensorFlow and OpenCV environment.
Who it is for
- Developers exploring 2D body or hand pose estimation.
- Practitioners who want to inspect multi-stage pose heatmaps or a single-hand tracking workflow.
- Researchers or developers preparing labeled pose data to train or distill a model.
Documented uses
- Estimate body or hand joints from an image, video file or webcam.
- View intermediate-stage heatmaps, final pose estimates or individual joint heatmaps.
- Explore single-hand tracking with Kalman-filter smoothing.
- Prepare labeled data and build a multi-stage pose model for training or teacher-student distillation.
Requirements & limits
The project is a public GitHub repository under the Apache 2.0 license.
- The README lists Windows 10 or Ubuntu 16.04, TensorFlow 1.4.0 and OpenCV 3.2.
- Demo scripts use pretrained model files placed in models/weights.
- The included model assumes the body or hand is near the center of the frame; the README suggests adding a detector and supplying a bounding-box crop when needed.
Check current requirements in the official documentation. Source-based guidance does not mean OpenViST has run or independently tested this project.
Run a hand-pose demo on an image or video
Use the hand demo script to estimate hand pose from an image, video, or webcam.
Before you start
- Windows 10 or Ubuntu 16.04; TensorFlow 1.4.0 and OpenCV 3.2 are the listed environment.
- A downloaded hand-pose model: .pkl or TensorFlow format. The webcam tracker specifically requires the TensorFlow-format model.
Steps
Place the downloaded model in the repository's models/weights folder.
In demo_cpm_hand.py, set DEMO_TYPE and provide an image path for image input; for webcam input, choose MULTI, SINGLE, or HM to select the displayed output.
Use a supported video file (.avi, .mp4, or .flv) when supplying video input.
For single-hand tracking, download the TensorFlow-format hand model and execute run_demo_hand_with_tracker.py.
Expected outcome
The hand demo estimates pose; webcam modes display stage heatmaps and/or final pose, and the tracker script provides single-hand tracking.
Guide limitations
- The model assumes the hand is located near the center of the frame. The README suggests adding a detector and feeding its detected bounding-box image to the model when needed.
- The README does not specify the exact input-setting procedure for video files.
Prepare data and configure a custom CPM training workflow
Prepare the dataset and set up the documented model and training components for a custom pose model.
Before you start
- A dataset organized under dataset/person_0/imgs/ with a corresponding dataset/person_0/labels.txt.
- Labels containing image filename, bounding-box coordinates, and joint coordinates in the documented order.
Steps
Use utils/create_cpm_tfr_fulljoints.py as the dataset-preparation example.
Format each labels.txt row as image filename, bbox_top_left_y, bbox_top_left_x, bbox_bot_right_y, bbox_bot_right_x, followed by joint y/x coordinate pairs.
Use a model definition under models/nets, such as models/nets/cpm_hand.py, and create a model instance.
Set the model to at least two stages; call build_loss for training and use self.train_op to optimize, following run_training.py.
Expected outcome
The documented dataset structure and model configuration are prepared for a custom training workflow.
Guide limitations
- The README points to run_training.py as an example but does not provide the full execution procedure or specify training parameters.
- The distillation workflow is only identified as a teacher-student process in run_training_distillation.py; detailed steps are not provided.
Sources & review
Source record details
- Source availability
- Active
- Sources checked
- 17 October 2026
- Original website title
- timctho/convolutional-pose-machines-tensorflow · Official homepage title · retained in its source language