Metadata-Version: 2.4
Name: 3dsem
Version: 0.1.11
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
```

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+).
  No GPU? See the Modal question below.
- Python 3.9 or newer
- About 10 GB of disk per model

`sem install` shows the download size, the license, and a GPU check, then
asks once before any bytes move. It is safe to interrupt and resumes where it
stopped. After install, inference runs fully offline.

## Models

`dales-utonia` is trained on [DALES](https://arxiv.org/abs/2004.11985) aerial
LiDAR and predicts 8 classes: ground, vegetation, buildings, cars, trucks,
poles, powerlines, fences. Its license is CC-BY-NC 4.0 (non-commercial) and
is shown before install.

`sem models` lists what is available and installed. Bare `sem` opens an
interactive picker.

## How do I make it more accurate?

Use a preset. Each one turns on more of the same three ideas: predict the
scene from several augmented views and vote (test-time augmentation), tile
the scene a second time at a half offset so no point sits on a tile edge
(overlapped voting), and clean up the labels afterwards (smoothing, island
removal, geometry rules).

- default: one pass with light smoothing
- `--med`: 4 voting views, overlapped tiling, island removal. Roughly 4x the
  time.
- `--high`: 6 views including flips and rotations, stronger smoothing,
  geometry rules for ground/vegetation/building confusions, per-class
  probability fields. Roughly 6x.
- `--ultra`: 9 views and the strongest smoothing. Roughly 9x.

An explicit flag always wins over a preset, so `--ultra --no-sieve` means
ultra without island removal.

## How do I make it faster?

`--low` is a single pass with no cleanup, the fastest option. If a preset is
mostly what you want, `--no-overlap` drops its second tiling pass, which is
about half its extra cost.

## Big buildings come out patchy or cut through. Why?

The scene is processed in square tiles, typically 50 m on a side. An object
bigger than one tile is predicted in pieces, and the pieces can disagree.
Two fixes that combine well:

- `--chunk-xy 100` makes the tiles bigger, so a large building fits in one.
  Costs GPU memory.
- `--overlap` (on automatically with `--med` and up) predicts a second pass
  at a half offset and votes, which removes most seam artifacts.

## It ran out of GPU memory

Lower `--chunk-xy`, try 35 and then 25. Smaller tiles need less VRAM, and
the extra seams they create are what `--overlap` is for.

## Poles or powerlines are disappearing

Presets from `--med` up turn on island removal, which absorbs clusters
smaller than 10 points into their surroundings. Thin objects are exactly
small clusters. Keep the filter but make it gentler with
`--sieve-min-pts 5`, or turn it off with `--no-sieve`.

## Can I hide the model's low-confidence guesses?

`--unclass 0.6` exports every point below 60% confidence as unclassified
instead of its best guess. To see where the model is unsure, `--entropy`
adds a 0..1 uncertainty field, `--margin` adds the gap between the top two
classes, and `--prob-dims` adds one probability field per class (grows the
file).

## I want individual objects, not just classes

`--panoptic vehicle:5x2.5` splits a class into instances using a typical
footprint in meters (length x width) and writes an `instance_id` per point.
Several classes at once: `--panoptic vehicle:5x2.5,pole:1x1`. Based on
[ALPINE](https://arxiv.org/abs/2503.13203), no extra training involved.

## Can I combine models?

`sem infer dales-utonia+dales-hag-utonia tile.las` runs every model in the
chain and merges their predictions with a vote: each model's per-class
probabilities are averaged, and the strongest combined evidence wins. Where
the models agree, the label sticks; exact ties go to the model you listed
first, so lead with your strongest.
The result carries an `agreement` field (what fraction of models agreed on
each point) and an `ens_member` field (which model drove each label). The
models must share the same class list. Each member also keeps its own
`tile_<model>_predictions` folder, so you can compare them individually.

## My file has no coordinate system

`--epsg 32610` declares it (use your zone's code). Only needed when the file
itself does not say.

## I don't have a GPU

`sem infer dales-utonia tile.las --modal` runs the GPU work in your own
[Modal](https://modal.com) account. One-time setup: `pip install modal`,
then `modal setup`. Conversion and export still happen on your machine; only
the prepared tiles travel.

## Can I rerun with different settings without reconverting?

Yes. The output folder is a self-contained job, named after your file and
the model (`tile_dales-utonia_predictions/`). Quality options (presets,
TTA, cleanup, export) never reconvert. Conversion options (`--epsg`,
`--ground-method`, `--hag`, ...) and changes to the input file itself
reconvert automatically; identical settings reuse the staged files. Every
model keeps its own job folder, so switching models never mixes results.

## A whole folder of tiles?

Pass the folder. Every `.las/.laz/.ply/.pcd` inside becomes one job, and
results land in `<model>_predictions/` inside it.

## Where does everything live?

Downloads go to `~/.trainer` (set `TRAINER_HOME` to move them). Your data
and results never go there: each job is a folder next to your input, or
under a default you set with `sem output <dir>`. `sem clean dales-utonia`
removes one model; `sem clean --all` removes everything sem ever downloaded.

## Every option

`sem infer --help` documents all of it. Add `--pick` to browse and edit
every option with arrow keys before running.

## 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.
