Metadata-Version: 2.4
Name: auspex3d
Version: 0.1.0
Summary: 3D object detection for LiDAR point clouds (and optional cameras), trained on your own data
Author: Md. Sohanur Islam Shuvo
License: AUSPEX3D END-USER LICENSE AGREEMENT (EULA)
        
        Copyright (c) 2026 Md. Sohanur Islam Shuvo (github.com/sohanurislamshuvo)
        ("Licensor"). All rights reserved.
        
        This End-User License Agreement governs use of the Auspex3D software, including
        its binary distributions, source code, model architecture, configuration
        files, documentation, and tools (the "Software"). By installing or using the
        Software you agree to these terms.
        
        1. LICENSE GRANT. Subject to this Agreement, Licensor grants you ("Licensee")
           a limited, non-exclusive, non-transferable, revocable license to:
           a) install and run the Software, in the binary form provided to you, on
              systems under your control;
           b) train, fine-tune, validate, and run models with the Software using
              Licensee's own data; and
           c) use the resulting model weights and predictions for Licensee's own
              internal business purposes.
        
        2. OWNERSHIP. The Software, its architecture, and all intellectual property
           therein remain the exclusive property of Licensor. Model weights that
           Licensee trains with the Software on Licensee's own data belong to
           Licensee; this does not transfer any rights in the Software itself.
        
        3. RESTRICTIONS. Except with Licensor's prior written permission, Licensee
           shall NOT:
           a) copy (other than as required to install and run), redistribute, sell,
              rent, lease, sublicense, or otherwise make the Software available to
              any third party;
           b) modify, adapt, translate, or create derivative works of the Software;
           c) decompile, disassemble, reverse engineer, or otherwise attempt to
              derive the source code, architecture details, or algorithms of the
              Software, except to the extent such restriction is prohibited by
              applicable law;
           d) use the Software or knowledge gained from it to develop a competing
              product or service; or
           e) remove or alter any copyright or proprietary notices.
        
        4. TERMINATION. This license terminates automatically if Licensee breaches
           this Agreement. Upon termination, Licensee must cease use and destroy all
           copies of the Software; Sections 2, 5, 6 and 7 survive termination, and
           Licensee's rights under Section 1(c) to weights already trained on
           Licensee's own data survive any termination not caused by breach.
        
        5. NO WARRANTY. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
           KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
           MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
        
        6. LIMITATION OF LIABILITY. IN NO EVENT SHALL LICENSOR BE LIABLE FOR ANY
           CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
           OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
           THE USE OR OTHER DEALINGS IN THE SOFTWARE.
        
        7. THIRD-PARTY COMPONENTS. Parts of the Software are adapted from open-source
           projects listed, with their licenses, in THIRD_PARTY_NOTICES.md, which is
           distributed with the Software. Those parts remain subject to their own
           licenses, and nothing in this Agreement limits any right those licenses
           grant. Licensee is responsible for the license terms of the data it trains
           on; public datasets such as nuScenes, KITTI and Waymo Open restrict
           commercial use, which extends to models trained on them.
        
        For licensing inquiries, contact the copyright holder.
        
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Requires-Dist: torch>=2.3
Requires-Dist: torchvision>=0.18
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: PyYAML>=6.0
Requires-Dist: tqdm>=4.60
Requires-Dist: pillow>=9.0
Provides-Extra: cu118
Requires-Dist: spconv-cu118>=2.3.6; extra == "cu118"
Provides-Extra: cu120
Requires-Dist: spconv-cu120>=2.3.6; extra == "cu120"
Provides-Extra: cu121
Requires-Dist: spconv-cu121>=2.3.6; extra == "cu121"
Provides-Extra: cu124
Requires-Dist: spconv-cu124>=2.3.6; extra == "cu124"
Provides-Extra: cu126
Requires-Dist: spconv-cu126>=2.3.6; extra == "cu126"
Provides-Extra: cpu
Requires-Dist: spconv>=2.3.6; platform_system == "Linux" and extra == "cpu"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.7; extra == "viz"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: shapely>=2.0; extra == "dev"
Dynamic: license-file

# Auspex3D

3D object detection for LiDAR point clouds, with optional camera fusion, trained
on your own data in a few lines of code. Auspex3D finds objects as oriented 3D boxes
(center, size, heading) in each scan.

Supported label formats: **CVAT point-cloud exports** (Kitti Raw Format 1.0, Sly
Point Cloud Format 1.0, Datumaro 3D 1.0), **KITTI** object detection, and a
**simple text format**. You can mix them in one training run. Point clouds can be
`.pcd`, `.bin` or `.npy` files.

## Install

```bash
pip install auspex3d
```

Wheels are built for Linux x86_64, Windows x86_64 and macOS Apple Silicon, on Python 3.10–3.13.
Training needs an NVIDIA GPU for any real dataset; inference also runs on the CPU.

The default `pillar` model is pure PyTorch and runs everywhere. The `voxel` and
`sparse` models also need [spconv](https://github.com/traveller59/spconv), built
for the CUDA version of your PyTorch. Let Auspex3D work out which build:

```bash
auspex3d doctor          # reports your PyTorch, GPU and spconv, and which models can run
auspex3d doctor --fix    # installs the matching spconv build
```

You can also pick the extra yourself: `pip install "auspex3d[cu126]"` (or `cu118`,
`cu120`, `cu121`, `cu124`). There is no spconv for macOS, so only the `pillar` model
runs there.

## Use

```python
from auspex3d import Auspex3D

model = Auspex3D(labelspace="labelspace.yaml")             # pillar model by default
model.train(data="data.yaml", epochs=30)                   # train on your own data
results = model.predict("scans/", save=True)               # detect

model = Auspex3D(weights="runs/api/best.pt")               # checkpoints are self-contained
model.val(data="data.yaml")
```

On Windows, call `.train()` from inside an `if __name__ == "__main__":` block in
your script. Every library that loads data in worker processes needs this.

Or use the console command:

```bash
auspex3d train   --data data.yaml --labelspace labelspace.yaml --model pillar
auspex3d predict --weights runs/train/best.pt --source scans/
auspex3d val     --weights runs/train/best.pt --data data.yaml
```

`predict` accepts a file, a folder, a NumPy array of points (`[N, 3]` or more:
x, y, z, then intensity), or a list of these. It returns one result per scan, in
the scan's own coordinate frame:

```python
{"scan": "000123", "path": "scans/000123.pcd", "num_points": 118734,
 "detections": [{"label": "car", "score": 0.91,
                 "box": [12.4, -3.1, -0.8, 4.5, 1.9, 1.6, 1.57]}]}   # x y z, length width height, heading
```

`save=True` also writes a JSON file and a top-down image of every scan, with its
boxes drawn on it.

## Models

| `model=` | What it is | Needs |
|---|---|---|
| `pillar` (default) | CenterPoint-PointPillars: the point cloud is flattened into a bird's-eye-view grid | PyTorch only |
| `voxel` | CenterPoint with a sparse 3D backbone: more accurate on large outdoor scenes | spconv |
| `sparse` | VoxelNeXt: fully sparse, fast at long range | spconv |

Two further options:

- `head="transfusion"` replaces the center head of a `pillar` or `voxel` model with a transformer query head (TransFusion-L).
- `cameras=True` also uses calibrated camera images when your data has them (BEVFusion-style). The model is trained to keep working when the cameras are missing. Training with camera images is available for KITTI-format sources; `predict()` runs camera models on the LiDAR alone.

## Your data

**`labelspace.yaml`** lists your classes. Their order sets the class ids.

```yaml
categories:
  - name: car
    aliases: [Car, Van]        # the names your label files use for this class
    group: vehicle             # optional: classes of similar size share a detection head
  - name: truck
    group: vehicle
  - name: pedestrian
    aliases: [Pedestrian, person]
ignore: [DontCare, Misc]       # labels to drop
```

A label that is neither a class, an alias nor ignored stops training with an
error. Dropping it silently would teach the model that those objects are background.

**`data.yaml`** has one entry per labelled batch:

```yaml
point_range: [-51.2, -51.2, -5.0, 51.2, 51.2, 3.0]   # optional: x/y/z min, then max, in metres
sources:
  - name: batch1
    path: exports/batch1/          # an unzipped CVAT export, a KITTI folder, or a folder of .txt labels
    split: train
  - name: batch2
    path: exports/batch2/
    format: cvat-sly               # optional: detected from the folder contents
    split: val                     # a val split gives you best.pt, validation logs and early stopping
```

| `format` | What `path` points to |
|---|---|
| `cvat-kitti-raw` | CVAT "Kitti Raw Format 1.0" export: the unzipped folder, or its `tracklet_labels.xml` |
| `cvat-sly` | CVAT "Sly Point Cloud Format 1.0" export, unzipped |
| `cvat-datumaro` | CVAT "Datumaro 3D 1.0" export, unzipped |
| `kitti` | KITTI object detection: `label_2/`, `velodyne/`, `calib/` and optionally `image_2/`. Only the points inside the front camera's view are used, because that is all KITTI labels |
| `txt` | one `.txt` per scan with one box per line: `x y z dx dy dz heading class`, or `x y z dx dy dz heading vx vy class` |

Tick "Save images" when exporting from CVAT, so the export includes the point
clouds. Otherwise, set `points_root:` to the folder that holds them. `.bin` files
are read as 4 floats per point (x, y, z, intensity); set `point_dims:` for other
layouts.

Coordinates: x forward, y left, z up. A box is its **center**, its length (along
the heading), width and height, and its heading in radians, counter-clockwise
from +x. Keep the intensity scale the same in training and prediction: 0–1 and
0–255 look like different sensors to the model.

## Pre-labelling workflow

Send predictions back to CVAT to label new scans faster:

```python
model.predict("new_scans/", export="cvat-kitti-raw")   # writes runs/predict/predictions.cvat-kitti-raw.zip
model.predict("new_scans/", export="cvat-sly")         # or the Sly point-cloud format
model.predict("new_scans/", export="txt")              # or text labels that work as a data.yaml source
```

In CVAT, open the task and choose *Actions → Upload annotations* with the
matching format. Frames are matched by file name, so predict on the same files
the task holds.

## Training

- **Validation.** With a `val` split, the model is validated every `val_every` epochs (default 5). `best.pt` keeps the weights with the best score, and `val_log.csv` records every check. The score (fitness) is the mean of two numbers. Center-distance mAP measures whether objects are found. 3D-IoU mAP measures how tightly the boxes fit: an IoU of 0.7 for vehicles, 0.5 for small classes. `patience=N` stops training after N checks without improvement.
- **Grow a model.** `transfer="old/best.pt"` starts a new labelspace from an existing model. Weights that still fit carry over; outputs for new classes start fresh.
- **Resume.** `resume="runs/api/last.pt"` continues an interrupted run where it stopped.
- **Settings.** Keyword arguments change training settings, for example `batch_size=8, lr=0.002, num_workers=4`. `config="train.yaml"` overrides any other setting of the preset.

## Trial and licensing

**Training is free for 30 days, in full: no key, no sign-up, no feature
limits.** The 30 days start with your first training run.

**Prediction, validation and export are never restricted.** They keep working
after the trial ends, on every model you have trained.

After 30 days, training needs a credential. Either kind goes in the same place:

```bash
export AUSPEX_LICENSE=AUSPEX-...        # a licence key, or
export AUSPEX_LICENSE=HLN1....          # an account token
                                        # or write it to ~/.auspex/license.key
```

- A **licence key** (`AUSPEX-...`) is issued to an organisation for a fixed term. One Auspex licence covers both Auspex3D and auspex-vision.
- An **account token** (`HLN1....`) is one you generate yourself, from the console of an account that has been granted access to Auspex3D.

Both are verified **offline**, against a public key built into the package.
Nothing contacts a server, so training works on machines without internet
access. Because nothing is checked online, a credential cannot be revoked early,
which is why every credential has an expiry date.

Get a key: **<https://heliontechltd.com/license>**

## License

Auspex3D is proprietary software under an End-User License Agreement. Licensed
users may install and run Auspex3D and train models on their own data; the
resulting weights are theirs. Copying, redistributing, modifying and reverse
engineering Auspex3D are prohibited.

Parts of Auspex3D are adapted from open-source projects: CenterPoint (MIT),
VoxelNeXt and OpenPCDet (Apache-2.0). Their notices ship with the package.

Models inherit the terms of the data they are trained on. Public datasets such as
nuScenes, KITTI and Waymo Open do not allow commercial use.

See <https://heliontechltd.com/license> for the terms and for licensing inquiries.
