ANIMA SALUKI — Wave-10 WARDOG

Paper: Unsupervised UAV 3D Trajectories Estimation with Sparse Point Clouds ArXiv: 2412.12716 — ICASSP 2025 Reference repo: lianghanfang/UnLiDAR-UAV-Est

What SALUKI does

Unsupervised 3D UAV trajectory estimation from sparse LiDAR point clouds for drone-defense perception. Zero labels required at training time. Clean-room implementation from the paper method; classical pipeline today (DBSCAN + spatiotemporal scoring + spline fit) with YOLO26 detection priors fused on top and a training scaffold that is ready to absorb a learnable stage.

Subsystems

Subsystem	Status	Where
Core pipeline	READY	src/anima_saluki/pipeline.py, clustering.py
Data ingestion	READY	src/anima_saluki/data/
Eval harness	READY	src/anima_saluki/eval.py, metrics.py
Trainer scaffold	READY	src/anima_saluki/train.py, schedule.py
Checkpoint mgr	READY	src/anima_saluki/checkpoint.py
YOLO26 fusion	READY	src/anima_saluki/yolo26.py
Export pipeline	READY*	src/anima_saluki/export.py
ROS2 adapter	READY	src/anima_saluki/ros2_adapter.py
Dual Docker	READY	docker/Dockerfile.{cuda,mlx}

* Export produces pipeline model card + manifest stubs today. Real ONNX / TensorRT binaries land once a learnable stage is wired in; the directory layout and serve-image contract already match what the production serve stack expects.

Quick start

uv venv .venv --python 3.11
source .venv/bin/activate
uv pip install -e ".[dev]"

# Single-sequence inference (synthetic)
python -m anima_saluki run --synthetic-frames 40

# Evaluation over a benchmark manifest
python -m anima_saluki eval --manifest /data/saluki/manifest.json \
  --output-json /artifacts/reports/project_saluki/eval.json

# Training scaffold (no gradients yet — exercises the full lifecycle)
python -m anima_saluki train --manifest /data/saluki/manifest.json \
  --epochs 2 --seed 42

Use real sequences:

python -m anima_saluki run --input-dir /path/to/xyz_frames --backend cuda

Benchmark manifest format

{
  "dataset": "mmaud",
  "version": "1.0",
  "samples": [
    {
      "id": "seq_000",
      "frames_dir": "relative/path/to/frames",
      "gt_trajectory": "relative/path/to/gt.xyz",
      "frame_extension": ".bin",
      "columns": 4,
      "split": "train"
    }
  ]
}

Paths are confined to the manifest directory by default. Pass --allow-external-paths to opt in to absolute / cross-tree paths.

Dual compute

Every entrypoint accepts --backend auto|mlx|cuda|cpu:

• MLX: Apple Silicon dev iteration (Mac Studio M-series)
• CUDA: GPU server (8× L4 on datai_srv7_development)
• CPU: CI / unit tests
• auto: MLX → CUDA → CPU

Backend parity is enforced via allclose_backend in device.py.

Repository layout

project_saluki/
├── assets/hero.html, hero.png
├── configs/default.toml
├── docker/Dockerfile.{cuda,mlx}, docker-compose.yaml
├── papers/2412.12716.pdf
├── prds/ PRD-01..06
├── tasks/ T-001..006
├── scripts/download_data.sh
├── src/anima_saluki/
│   ├── __main__.py             # CLI: run / eval / train
│   ├── _io.py                  # atomic_write_text helper
│   ├── config.py               # pydantic-backed TOML config
│   ├── device.py               # MLX/CUDA/CPU resolver + parity
│   ├── pointcloud.py           # XYZ I/O
│   ├── clustering.py           # DBSCAN + tracking + scoring
│   ├── trajectory.py           # spline fit + RMSE
│   ├── pipeline.py             # end-to-end unsupervised pipeline
│   ├── data/                   # benchmark loaders + manifest + bundles
│   ├── metrics.py              # ADE / FDE / RMSE / trajectory IoU
│   ├── eval.py                 # manifest-driven evaluation harness
│   ├── schedule.py             # CosineWarmup + PlateauReduce
│   ├── checkpoint.py           # crash-safe top-k checkpoint manager
│   ├── train.py                # trainer scaffold (seed/split/ckpt/history)
│   ├── export.py               # pipeline graph + ONNX/TRT manifests
│   ├── yolo26.py               # YOLO26 contract + fusion
│   └── ros2_adapter.py         # import-safe ROS2 publisher stub
└── tests/                      # 64 tests, all green

Notes

• Verification status: paper real, reference repo incomplete. See NEXT_STEPS.md for the red-flag log.
• This module does not claim full reproduction of challenge metrics yet. The scaffold is ready to start real training on the 1.8M Mega UAV pool once NIGHTHAWK finishes building the mega dataset.
• See PRD.md, prds/, and tasks/ for the phase plan.