Motoki098/tennis-lab-models

日本語

Tennis-Lab detector inference checkpoints

These are inference checkpoints for the 2D court and ball detectors used in Tennis-Lab's synchronized multiview 3D reconstruction. They estimate court geometry, camera pose, and 2D ball positions from each camera's RGB images; the Tennis-Lab pipeline performs the 3D reconstruction. They require the linked repository's model and preprocessing code. Training state has been removed; every model tensor and the saved hyper_parameters are unchanged. The court checkpoint includes the frozen DINOv3 ViT-B/16 backbone.

Code / reproduction commit: 0a27bf13459a221f126805ed520a8eb8f59833a8 (source).

Inputs and outputs

Detector	Input	Output
Court	RGB image. The public API accepts PIL/NumPy RGB, resizes and pads to the saved settings (long edge 512, patch size 16), and applies ImageNet normalization. Prepared tensors must be float32 (1,3,H,W) with the same normalization.	Ordered KP14, 7-class segmentation, binary court lines, 12-class semantic lines, and raw camera pose10d. The repository's inference code provides per-head APIs and hybrid homography.
Ball	float32 RGB (B,T,3,H,W) in [0,1]. The standard pipeline uses 8-frame windows resized to 288×512. The predictor applies the saved ImageNet normalization and 2-channel MDD transform.	Native sigmoid heatmaps (B,T,H/4,W/4), 2D coordinates normalized by the grid endpoints, confidence, and candidate points. Scores are uncalibrated and are not presence probabilities.

The court model uses DINOv3 + Transformer + multiscale DPT (dense head residual depth 3); the ball model is a ConvNeXt spatiotemporal U-Net. Both remain Lightning .ckpt files with training state removed, retaining every model tensor, the complete hyper_parameters, pytorch-lightning_version, and hparams_name. They contain no optimizer, scheduler, loop, callback, or epoch/global_step state. The inference code is unchanged.

The canonical input contracts and usage instructions are the court README and ball README.

Download and verification

Prepare Tennis-Lab at the commit above, then run these commands from the repository root.

.venv/bin/python -m src.utils.model_weights --checkpoint-root "$PWD/ckpt"
.venv/bin/python -m src.utils.model_weights --checkpoint-root "$PWD/ckpt" --verify-only

Use --model court or --model ball to select one detector. The CLI verifies the downloads' SHA-256 before installation; mismatches or missing files are errors. It does not automatically overwrite existing files with different contents. Paths in this Hub repository can be used unchanged as paths relative to Tennis-Lab's ckpt/. Load the .ckpt files with this repository's code; they are not in Transformers' from_pretrained format.

Even though the public court checkpoint includes the backbone, the current court loader requires the third_party/dinov3 code and ckpt/dinov3/dinov3_vitb16_pretrain_lvd1689m-73cec8be.pth when constructing the model. These upstream assets and other pipeline assets such as GVHMR and SMPL are not included in this Model repository; see the required assets in the installation guide.

SHA-256

Checksums for the published inference checkpoints with training state removed, which retain the training checkpoint filenames, are listed in SHA256SUMS, and the download CLI independently verifies the files against the values pinned in its code.

Reproduction and CPU verification

The export script pins the original training checkpoints by SHA-256 and generates the inference versions. Keeping the .ckpt format allows the existing strict loaders to use the saved model configuration, preprocessing, and target bundle directly. The filenames also match the standard pipeline configuration.

The following checks used CPU float32 with seed 42. Both detectors used the production predictors' strict loading paths. For the court detector, the input adapter prepared DINOv3's four feature stages and all model heads were executed.

Detector	Small input shape	Compared outputs	Maximum absolute difference
Court	(1,3,32,32)	kp / seg / line / semantic_line logits + pose10d	0
Ball	(1,8,3,32,32)	heatmaps + coords + confidence	0

All 593 court tensors, all 242 ball tensors, and hyper_parameters also matched the original versions exactly. This verifies equivalence of the conversion to inference checkpoints; it is not an accuracy evaluation on real videos or a GPU execution result.

Training provenance and terms

This repository contains ball and court detector weights under different licenses. See the root LICENSE for the scope and full text of each license, and the project's weight license basis.

The ball detector weights, ball_detection/i935-mixed-ft-s42-epoch09.ckpt, are under CC BY-NC 4.0. The initial training was from scratch, without external pretrained weights; the basis for this initialization provenance is the user's response on 2026-10-19. Training used TrackNet, Meiji, and additional ball annotations from YouTube.

The court detector weights, court_detection/multiscale_depth3/b863df1f01f0.ckpt, are under the DINOv3 License. They include Meta's DINOv3 ViT-B/16 parameters and were trained on a mixture of real images from TennisCourtDetector and synthetic images from Synthetic Court B00–B03. Use, redistribution, and research publications must follow that license. No separate project-specific noncommercial restriction or CC BY-NC 4.0 license is added to the court weights.

Training was for information analysis to estimate ball positions and court geometry. Publication of the ball weights is based on the project's judgment that Article 30-4 of Japan's Copyright Act applies to the use during training. That article excludes cases that would unreasonably prejudice the interests of the copyright owner. See the e-Gov statutory text and Agency for Cultural Affairs material.

Third-party training videos, images, and datasets themselves are not included. The judgment above does not mean that the sources' contractual terms or permissions at acquisition have been resolved; unconfirmed matters remain.

The intended uses are research and noncommercial demos. This description adds no use restrictions to the respective licenses. Separately used assets such as GVHMR, SMPL, and SMPL-X, and pipeline outputs, remain subject to their respective terms; see pipeline output terms.

Attribution example for the ball checkpoint: Motoki0705 / Motoki098, “Tennis-Lab ball detector”, 2026, model repository, CC BY-NC 4.0. For the court checkpoint, retain and follow the DINOv3 License in LICENSE, including acknowledgment of DINOv3 when publishing research results.