Metadata-Version: 2.4
Name: prism-lidarcloud
Version: 1.2.4
Summary: Official Python client + CLI for PRISM LiDAR Cloud — one call turns raw LiDAR into a survey-grade deliverable set: DEM/DSM/CHM, classified cloud, per-cell uncertainty, automatic co-registration, change detection, true-colour drape, CAD bundle, and an AI-assisted accuracy report.
Author: PRISM LiDAR Cloud
License: MIT
Project-URL: Homepage, https://lidarcloud.app
Project-URL: Documentation, https://app.lidarcloud.app/docs/api
Keywords: lidar,dem,dsm,chm,point-cloud,gis,remote-sensing,geospatial
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# prism-lidarcloud

Official Python client and command line tool for the [PRISM LiDAR Cloud](https://lidarcloud.app)
REST API. One command uploads a `.las` or `.laz` point cloud, runs the cloud pipeline, waits for the
job to finish, and downloads the product zip.

By default, PRISM runs the full deliverable suite:

- USGS 3DEP alignment by AutoSnap™, baked into aligned deliverable copies
- bare-earth DEM, DSM, canopy height model, and DEM uncertainty rasters by Stratum™
- NAVD88 / GEOID18 orthometric heights by default, with EGM2008 orthometric output outside CONUS when available
- 8-class ASPRS ground + semantic classified point cloud by Stratum™
- true-colour drape for no-RGB clouds when imagery is available
- 3DEP change comparison, plus a raw 3DEP point-cloud engine pass for same-engine DEM and canopy change
- Verus™ accuracy report with Metria™ narrative
- SurveyPack™ CAD / survey bundle: DXF and LandXML
- email notification when the job finishes

The package has no third-party Python dependencies.

## Install

Windows PowerShell:

```powershell
py -m pip install --upgrade prism-lidarcloud
```

macOS / Linux:

```bash
python3 -m pip install --upgrade prism-lidarcloud
```

## Get and set an API key

Sign in at <https://app.lidarcloud.app>, open your account menu, choose **API access**, then choose
**Create API key**. The key starts with `prism_live_` and is shown once. Keep it private.

Set it for the current terminal session:

Windows PowerShell:

```powershell
$env:PRISM_API_KEY = "prism_live_xxxxxxxxxxxx"
```

macOS / Linux:

```bash
export PRISM_API_KEY="prism_live_xxxxxxxxxxxx"
```

Optional persistent setup:

Windows PowerShell:

```powershell
[Environment]::SetEnvironmentVariable("PRISM_API_KEY", "prism_live_xxxxxxxxxxxx", "User")
```

macOS zsh:

```bash
echo 'export PRISM_API_KEY="prism_live_xxxxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc
```

## Run a job

Windows PowerShell:

```powershell
prism run "C:\surveys\scan.las" --out products.zip
```

macOS / Linux:

```bash
prism run ./scan.las --out products.zip
```

That is the normal copy/paste path: upload, process, wait, and download the complete product zip.

## Common CLI commands

```bash
prism run scan.las --out products.zip
prism submit scan.las
prism status <job_id>
prism download <job_id> --out products.zip
prism jobs
```

Common opt-out flags (in spine order: classification, colorization, change, report, narrative, delivery):

```bash
prism run scan.las --out products.zip --no-classify
prism run scan.las --out products.zip --no-change
prism run scan.las --out products.zip --no-dep3-cloud
prism run scan.las --out products.zip --no-report --no-narrate
prism run scan.las --out products.zip --no-cad --no-notify
```

Other useful flags (in spine order: upload, alignment, DEM, colorization):

```bash
prism run scan.las --reference prior_survey.las --out products.zip
prism run scan.las --out products.zip --dem-res 50cm
prism run scan.las --out products.zip --vdatum ellipsoidal
prism run scan.las --out products.zip --colorize on --colorize-source naip
```

Default option values (in spine order: upload, alignment, DEM, classification, colorization, change, report, narrative, delivery):

| Option | Default | Notes |
| --- | --- | --- |
| `--reference` | none | Upload a second cloud as the reference; sets `--align upload`. |
| `--ref-site` | none | Align to an already processed site; sets `--align existing`. |
| `--align` | `3dep` | AutoSnap™. Choices: `none`, `3dep`, `upload`, `existing`. Default uses USGS 3DEP as the reference. |
| `--bake` | on | AutoSnap™. Bakes alignment into aligned deliverable copies. Use `--no-bake` to skip. |
| `--dem-res` | `25cm` | Stratum™ DEM / DSM / CHM. Choices: `auto`, `25cm`, `50cm`, `100cm`, `250cm`, `5m`, `10m`. |
| `--vdatum` | `navd88` | Stratum™. Choices: `navd88`, `egm2008`, `ellipsoidal`. NAVD88/GEOID18 by default; outside CONUS PRISM uses EGM2008 when available. Use `ellipsoidal` only when you explicitly want WGS84 ellipsoidal heights. |
| classification | on | Stratum™ ground + semantic classification (runs after the DEM it depends on). Use `--no-classify` to skip. |
| `--colorize` | `auto` | Choices: `auto`, `on`, `off`. Runs for no-RGB clouds when imagery is available. |
| `--colorize-source` | `auto` | Choices: `auto`, `sentinel`, `naip`, `fusion`. |
| change detection | on | Use `--no-change` to skip. |
| 3DEP point-cloud pass | on | Use `--no-dep3-cloud` for faster screening-grade DEM-only 3DEP change. |
| accuracy report | on | Verus™. Use `--no-report` to skip. |
| narrative | on | Metria™. Use `--no-narrate` to skip. |
| CAD bundle | on | SurveyPack™. Use `--no-cad` to skip. |
| email notification | on | Use `--no-notify` to skip. |

## Python

```python
from prism_lidarcloud import Client

c = Client()  # reads PRISM_API_KEY
out = c.run("scan.las", out="products.zip")
print("saved", out)
```

Step by step:

```python
from prism_lidarcloud import Client

c = Client()
job = c.submit("scan.las")
final = c.wait(job["job_id"], on_progress=lambda d: print(d["status"], d["pct"], d["stage"]))
c.download(job["job_id"], "products.zip")
```

All main upload options are also Python keyword arguments:

```python
c.run(
    "scan.las",
    out="products.zip",
    # alignment (AutoSnap)
    align="3dep",
    bake=True,
    # DEM / DSM / CHM (Stratum)
    dem_res="25cm",
    vdatum="navd88",
    # classification (Stratum, after the DEM)
    classify=True,
    # colorization
    colorize="auto",
    colorize_source="auto",
    # change
    change=True,
    dep3_cloud=True,
    # accuracy report (Verus)
    report=True,
    # narrative (Metria)
    narrate=True,
    # CAD bundle (SurveyPack)
    cad=True,
    # delivery
    notify=True,
)
```

## Large uploads and fast downloads

Large uploads automatically use WarpStream™ accelerated direct transfer when the server supports
it. Very large clouds are automatically tiled and merged by HyperScale™ behind the scenes —
no option to set. For paired jobs, both the target cloud and uploaded reference cloud use the same
fast transfer path when either file crosses the fast-upload threshold. The default is 100 parallel
streams, and downloads use the same stream cap on the fast download path. Most users do not need to
change this.

Advanced:

Windows PowerShell:

```powershell
$env:PRISM_PARALLEL_STREAMS = "100"
prism run "C:\surveys\large_scan.las" --out products.zip
```

macOS / Linux:

```bash
PRISM_PARALLEL_STREAMS=100 prism run ./large_scan.las --out products.zip
```

Downloads use the fast parallel download path by default. Use `--standard-download` only when an
operator intentionally needs the slower server-built zip path:

```bash
prism download <job_id> --out products.zip
prism download <job_id> --out products_standard.zip --standard-download
```

The fast path includes the complete stored product tree: rasters, clouds, report, CAD, FGDC metadata,
alignment, change products, colorization sidecars, and export sidecars.

## REST quickstart

macOS / Linux:

```bash
KEY="prism_live_xxxxxxxxxxxx"

curl -sS -X POST https://app.lidarcloud.app/api/v1/jobs \
  -H "Authorization: Bearer $KEY" \
  -F file=@scan.las

# replace <job_id> with the returned job_id
curl -sS https://app.lidarcloud.app/api/v1/jobs/<job_id> \
  -H "Authorization: Bearer $KEY"

curl -sS -L https://app.lidarcloud.app/api/v1/jobs/<job_id>/download \
  -H "Authorization: Bearer $KEY" -o products.zip
```

Windows PowerShell:

```powershell
$KEY = "prism_live_xxxxxxxxxxxx"

curl.exe -sS -X POST "https://app.lidarcloud.app/api/v1/jobs" `
  -H "Authorization: Bearer $KEY" `
  -F "file=@C:\surveys\scan.las"

# replace <job_id> with the returned job_id
curl.exe -sS "https://app.lidarcloud.app/api/v1/jobs/<job_id>" `
  -H "Authorization: Bearer $KEY"

curl.exe -sS -L "https://app.lidarcloud.app/api/v1/jobs/<job_id>/download" `
  -H "Authorization: Bearer $KEY" `
  -o products.zip
```

Full API docs: <https://app.lidarcloud.app/docs/api>

## Troubleshooting

- `No API key`: set `PRISM_API_KEY` or pass `--token prism_live_...`.
- `401`: the key is missing, invalid, or revoked.
- `402 confirm_required`: the job's cost estimate exceeds the account's confirmation cap. Re-submit
  with `--confirm` (CLI) or `confirm=True` (Python), optionally with `--max-usd N` / `max_usd=N`.
- `413`: the file exceeds the current upload or automated processing limit.
- `429`: wait and retry; the API is rate limiting requests.
