Metadata-Version: 2.4
Name: 3dsem
Version: 0.1.8
Summary: Classify point clouds with pretrained 3D semantic segmentation models, from one command
License: MIT
License-File: LICENSE
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# 3dsem

Classify point clouds with pretrained 3D semantic segmentation models, on
your own machine, from one command.

```
pip install 3dsem

sem install dales-utonia
sem infer dales-utonia tile.las
```

That's the whole workflow. The classified `.laz` appears next to your input
file, with per-point classification, confidence, and every original dimension
carried over.

## What you need

- An NVIDIA GPU with a current driver (Windows 527.41+, Linux 525.60.13+),
  or a [Modal](https://modal.com) account for cloud runs with `--modal`
- Python 3.9 or newer
- About 10 GB of disk per model

`sem install` downloads a model together with its exact, tested runtime in
one step. After install, inference runs fully offline.

## Models

| Model | Trained on | License |
|---|---|---|
| `dales-utonia` | [DALES](https://arxiv.org/abs/2004.11985) aerial LiDAR (8 classes: ground, vegetation, buildings, cars, trucks, poles, powerlines, fences) | CC-BY-NC 4.0 (non-commercial) — shown before install |

## Commands

```
sem                  interactive picker (choose a model, run it)
sem models           list available and installed models
sem install <model>  one-time model download
sem infer <model> <input> [output]
sem output [<dir> | off]   default output directory (unset: results land
                           next to the input)
sem clean [<model> | --all]
```

`infer` accepts a `.las`/`.laz`/`.ply`/`.pcd` file or a whole folder, and
converts it automatically using the model's own training recipe. By default
it does a fast single pass with light smoothing; the effort presets trade
time for accuracy:

```
sem infer dales-utonia tile.las --ultra            max accuracy: 9-view TTA,
                                                   full cleanup (~9x time;
                                                   also --med, --high, --low)
sem infer dales-utonia tile.las --unclass 0.6      low-confidence points
                                                   become unclassified
sem infer dales-utonia tile.las --panoptic vehicle:5x2.5
                                                   split a class into
                                                   individual objects
sem infer dales-utonia tile.las --modal            run on Modal instead of
                                                   a local GPU
sem infer dales-utonia tile.las --pick             browse every option with
                                                   arrow keys, then run
```

Every option is documented in `sem infer --help`.

## What the extras are

- **TTA & overlapped voting** — the model predicts the scene from several
  augmented views and overlapping tiles, then votes; slower, more robust.
- **Cleanup passes** — KNN probability smoothing (in the spirit of
  [RangeNet++](https://github.com/PRBonn/rangenet_lib)), small-island
  removal, and height/planarity rules for ground/vegetation/building
  confusions.
- **Height Above Ground** — when a model uses it, ground is detected with
  [CSF](https://github.com/jianboqi/CSF) or
  [SMRF](https://pdal.io/en/latest/stages/filters.smrf.html) and the channel
  is computed from your cloud automatically.
- **`--panoptic`** — training-free instance clustering with
  [ALPINE](https://github.com/valeoai/Alpine)
  ([paper](https://arxiv.org/abs/2503.13203)): give a typical object
  footprint per class and get an `instance_id` per point.

## Where things live

All downloads go to `~/.trainer` (set `TRAINER_HOME` to move them);
`sem clean --all` removes everything. Your data and results never go there —
each job is one folder next to your input (or under your `sem output` dir):
the staged+classified `.npz`, a `job.json` record, and the exported `.laz`.

## Licensing

The `sem` tool is MIT licensed. Each model ships a `NOTICE.md` stating its
architecture credits and license terms; some models carry a non-commercial
restriction inherited from their pretrained components, shown before you
install.
