Skip to content

Commit c47be72

Browse files
HeDo88THHeDo88TH
committed
Updated docs
1 parent f8718c4 commit c47be72

31 files changed

Lines changed: 806 additions & 550 deletions

‎docs/cli.mdx‎

Lines changed: 0 additions & 407 deletions
This file was deleted.

docs/_cli_autogen.mdx renamed to docs/cli/_cli_autogen.mdx

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,28 @@ Usage:
147147
148148
```
149149

150+
### contour
151+
152+
```
153+
Generate contour lines (GeoJSON) from a DEM/DSM/DTM raster.
154+
155+
Usage:
156+
ddb contour [options] input.tif [args]
157+
158+
--input arg Input single-band raster (DEM/DSM/DTM)
159+
-o, --output arg Output GeoJSON file (default: stdout)
160+
-i, --interval arg Vertical interval between contour levels (raster units) (default: 0)
161+
-n, --count arg Target number of contour levels (used when --interval is 0) (default: 0)
162+
-b, --base arg Reference base elevation (default: 0)
163+
--min arg Drop contours below this elevation (default: nan)
164+
--max arg Drop contours above this elevation (default: nan)
165+
-s, --simplify arg Geometry simplification tolerance (raster CRS units) (default: 0)
166+
--band arg 1-based raster band index (default: 1)
167+
-h, --help Print help
168+
--debug Show debug output
169+
170+
```
171+
150172
### geoproj
151173

152174
```

‎docs/cli/cli-reference.mdx‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
---
2+
sidebar_position: 4
3+
description: 'Command Line Interface for DroneDB'
4+
---
5+
6+
import CLIAutogen from './_cli_autogen.mdx';
7+
import TOCInline from '@theme/TOCInline';
8+
import Tabs from '@theme/Tabs';
9+
import TabItem from '@theme/TabItem';
10+
11+
# Reference
12+
13+
`ddb` is a command line interface (CLI) to access DroneDB's functions. This makes it ideal for power users and for creating automated workflows.
14+
15+
See the [CLI Overview](/docs/cli) page for a quick command summary and links to tutorials.
16+
17+
## Quick Examples
18+
19+
Below are concise examples for commands not covered in the [Examples](/docs/cli/examples) page.
20+
21+
### Projecting images
22+
23+
Project images onto a georeferenced map:
24+
25+
```bash
26+
ddb geoproj images/DJI_0018.JPG -o projected/
27+
```
28+
29+
### Creating static tiles (XYZ/TMS)
30+
31+
Generate tiles for GeoTIFFs, drone images and [COPC](https://github.com/OpenDroneMap/cloud-optimized-point-cloud) point clouds. Similar to [gdal2tiles.py](https://gdal.org/programs/gdal2tiles.html) but faster and with more format support:
32+
33+
```bash
34+
ddb tile DJI_0018.JPG output_tiles/
35+
ddb tile orthophoto.tif output_tiles/
36+
```
37+
38+
### Building COPC point clouds
39+
40+
Build COPC (Cloud Optimized Point Cloud) files for efficient streaming:
41+
42+
```bash
43+
ddb copc output/ point_cloud.laz
44+
```
45+
46+
Supported input formats: LAS, LAZ, E57, PTS, XYZ, PLY.
47+
48+
### Generating Cloud Optimized GeoTIFFs (COG)
49+
50+
Convert standard GeoTIFFs to COGs for efficient streaming with range requests:
51+
52+
```bash
53+
ddb cog output.tif input.tif
54+
```
55+
56+
### Extracting GPS locations/footprints to GeoJSON
57+
58+
```bash
59+
# GPS points
60+
ddb info *.JPG -f geojson -o gps.geojson
61+
62+
# Image footprints (polygons)
63+
ddb info *.JPG -f geojson --geometry polygon -o footprint.geojson
64+
```
65+
66+
### Generating STAC Catalogs
67+
68+
Generate STAC-compliant JSON for interoperability:
69+
70+
```bash
71+
cd my-dataset/
72+
ddb stac
73+
74+
# For a specific file
75+
ddb stac -p orthophoto.tif
76+
```
77+
78+
### Building 3D Model Tiles (Nexus)
79+
80+
Generate Nexus files for efficient web streaming of 3D meshes:
81+
82+
```bash
83+
ddb nxs model.obj output.nxz
84+
```
85+
86+
Supported input formats: OBJ, GLTF, GLB.
87+
88+
### Generating Thumbnails
89+
90+
```bash
91+
ddb thumbs *.JPG -o thumbs/
92+
ddb thumbs orthophoto.tif -o thumb.jpg -s 1024
93+
```
94+
95+
### Re-processing indexed files after an upgrade
96+
97+
When you upgrade DroneDB to a version that extracts additional metadata or supports new file types, use `rescan` to update all metadata in place:
98+
99+
```bash
100+
cd my-dataset/
101+
ddb rescan
102+
103+
# Only specific types
104+
ddb rescan --type image,pointcloud
105+
106+
# Continue even if some files fail
107+
ddb rescan --continue-on-error
108+
```
109+
110+
## Environment Variables
111+
112+
:::tip
113+
For practical workflow examples (multispectral, terrain analytics, clone/push, metadata), see the [Examples](/docs/cli/examples) page.
114+
:::
115+
116+
DroneDB reads the following environment variables at runtime. Variables marked **GDAL config** can also be set via `CPLSetConfigOption()` in the GDAL C API.
117+
118+
### General
119+
120+
| Variable | Description |
121+
|----------|-------------|
122+
| `DDB_LOG` | If set (any value), enables logging to file (`ddb-log.csv`) in the current directory. |
123+
| `DDB_DEBUG` | If set (any value), enables verbose debug output on the console. Equivalent to passing `--debug`. |
124+
| `DDB_HOME` | Override the DDB home directory (default: `~/.ddb`). Stores credentials and user profile. |
125+
| `DDB_DATA` | Override the DDB data directory used for bundled data files (timezone database, etc.). |
126+
127+
### Point Cloud (COPC/EPT)
128+
129+
| Variable | Description |
130+
|----------|-------------|
131+
| `DDB_UNTWINE_PATH` | Absolute path to the `untwine` binary. When set, this path is authoritative: if it does not point to a valid executable, Untwine is considered unavailable. Useful for pinning the backend or running tests. |
132+
| `DDB_USE_PDAL_COPC` | Set to `1` to force the PDAL COPC backend, bypassing Untwine. |
133+
| `DDB_COPC_BACKEND` | Explicit backend selection: `"untwine"`, `"pdal"`, or `"auto"` (default). Unknown values are silently ignored. `DDB_USE_PDAL_COPC=1` takes precedence. |
134+
135+
### COG Build (GDAL config)
136+
137+
These variables control `ddb build` and `ddb cog` for GeoRaster entries. They are read via `CPLGetConfigOption` and can also be passed as standard environment variables.
138+
139+
| Variable | Default | Description |
140+
|----------|---------|-------------|
141+
| `DDB_COG_JPEG_QUALITY` | `75` | JPEG quality (1–100) for COG compression. Applied only to 8-bit RGB or RGBA rasters. LZW is used for all other cases. |
142+
| `DDB_WARP_MEMORY_MB` | `512` | GDALWarp memory buffer size in MB (`-wm` flag). Larger values reduce chunking overhead when multi-threading is active. |
143+
| `DDB_COG_CACHE_MB` | `1024` | GDAL block cache size in MB during COG build. Raised temporarily before the warp and restored afterwards. |
144+
145+
## Commands Reference
146+
147+
<CLIAutogen />

‎docs/cli/examples.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
sidebar_position: 3
3+
sidebar_label: Examples
4+
---
5+
6+
# CLI Examples
7+
8+
Practical examples of common DroneDB CLI workflows.
9+
10+
## Glob Patterns
11+
12+
`ddb` accepts shell-style glob patterns wherever a path or list of paths is expected:
13+
14+
| Pattern | Matches |
15+
|---------|---------|
16+
| `*.JPG` | All `.JPG` files in the current directory |
17+
| `images/*.tif` | All `.tif` files directly under `images/` |
18+
| `**/*.las` | All `.las` files recursively |
19+
| `images/**/*` | All files under `images/`, recursively |
20+
| `images/` | The directory itself plus everything under it |
21+
22+
Some shells (POSIX shells, PowerShell) expand globs before passing them to `ddb`. Quote the pattern (e.g., `'**/*.JPG'`) if you want `ddb` to handle the expansion.
23+
24+
## Sharing Datasets
25+
26+
Share images to [Hub](https://hub.dronedb.app) or a self-hosted Registry:
27+
28+
```bash
29+
# Share to Hub (default)
30+
ddb share *.JPG
31+
32+
# Share to a specific server
33+
ddb share *.JPG -s http://localhost:5000
34+
35+
# Share with a specific tag
36+
ddb share *.JPG -t my-org/my-dataset
37+
```
38+
39+
Tags follow the format: `[server]/organization/dataset` (server is optional).
40+
41+
## Clone, Edit, and Push Workflow
42+
43+
Clone an existing dataset, make modifications offline, then sync back:
44+
45+
```bash
46+
# 1. Clone a dataset from Hub
47+
ddb clone pierotofy/brighton-beach
48+
49+
# 2. Add new files
50+
cd brighton-beach/
51+
ddb add README.md new_photos/*.JPG
52+
53+
# 3. Push changes back
54+
ddb push
55+
56+
# 4. (Optional) Change destination tag
57+
ddb tag http://localhost:5000/my-org/brighton-copy
58+
ddb push
59+
```
60+
61+
## Metadata Management
62+
63+
Store custom JSON metadata on files or the entire dataset:
64+
65+
```bash
66+
# Dataset-level metadata
67+
ddb meta set pilot '{"name": "John Smith"}'
68+
ddb meta get pilot --format json
69+
70+
# File-level metadata
71+
ddb add photo.JPG
72+
ddb meta add comments '{"text": "Nice one!", "author": "John S."}' -p photo.JPG
73+
ddb meta get comments -p photo.JPG --format json
74+
```
75+
76+
Plural keys (ending with `s`) are treated as lists; singular keys are single objects. Metadata is synced on push/pull.
77+
78+
## Multispectral Workflow
79+
80+
A typical flow for multispectral survey data processed with OpenDroneMap:
81+
82+
```bash
83+
# 1. Index the original raw captures
84+
ddb add images/
85+
86+
# 2. Merge per-band orthophotos from ODM output
87+
ddb merge-multispectral \
88+
-o odm_orthophoto/multispectral.tif \
89+
odm_orthophoto/odm_orthophoto_blue.tif \
90+
odm_orthophoto/odm_orthophoto_green.tif \
91+
odm_orthophoto/odm_orthophoto_red.tif \
92+
odm_orthophoto/odm_orthophoto_nir.tif \
93+
odm_orthophoto/odm_orthophoto_rededge.tif
94+
95+
# 3. Mask border pixels
96+
ddb mask odm_orthophoto/multispectral.tif
97+
98+
# 4. Add the merged result to the index
99+
ddb add odm_orthophoto/multispectral_masked.tif
100+
101+
# 5. Share or push to Hub
102+
ddb push
103+
```
104+
105+
## Terrain Analytics
106+
107+
### Generate contour lines
108+
109+
```bash
110+
# Contours every 10 m, simplified to 1 m
111+
ddb contour dem.tif -o contours.geojson -i 10 -s 1
112+
113+
# 20 evenly spaced levels
114+
ddb contour dem.tif -o contours.geojson -n 20
115+
```
116+
117+
### Mask orthophoto borders
118+
119+
```bash
120+
# Remove black borders
121+
ddb mask orthophoto.tif
122+
123+
# Custom tolerance and output
124+
ddb mask orthophoto.tif -o output.tif
125+
126+
# Search for white borders
127+
ddb mask orthophoto.tif -w
128+
```
129+
130+
### Align rasters to a reference
131+
132+
Correct georeferencing offsets by aligning to a more accurate reference:
133+
134+
```bash
135+
# Similarity transform (default: translation + rotation + scale)
136+
ddb align -i source.tif -r reference.tif -o aligned.tif
137+
138+
# Translation only (faster)
139+
ddb align -i source.tif -r reference.tif -o aligned.tif -m translation
140+
141+
# Validate without applying
142+
ddb align -i source.tif -r reference.tif --validate
143+
```
144+
145+
## See Also
146+
147+
- [CLI Command Reference](/docs/cli/cli-reference)
148+
- [Features: Multispectral & Thermal](/docs/features/multispectral)
149+
- [Features: Terrain Analytics](/docs/features/terrain-analytics)

‎docs/cli/index.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
sidebar_position: 1
3+
sidebar_label: CLI Overview
4+
---
5+
6+
# CLI Overview
7+
8+
`ddb` is a command-line interface (CLI) to access DroneDB's functions. It's ideal for power users and for creating automated workflows.
9+
10+
## Quick Reference
11+
12+
| Command | Description |
13+
|---------|-------------|
14+
| `ddb init` | Initialize a new DroneDB index |
15+
| `ddb add` | Add files to the index |
16+
| `ddb rm` | Remove files from the index |
17+
| `ddb list` | List indexed files |
18+
| `ddb search` | Search indexed files |
19+
| `ddb build` | Generate derivative products (tiles, thumbnails, etc.) |
20+
| `ddb share` | Share files to Hub/Registry |
21+
| `ddb push` | Sync local index to Registry |
22+
| `ddb pull` | Pull changes from a remote Registry |
23+
| `ddb clone` | Clone a remote dataset |
24+
| `ddb info` | Show file metadata |
25+
| `ddb contour` | Generate contour lines from DEMs |
26+
| `ddb mask` | Mask orthophoto borders |
27+
| `ddb merge-multispectral` | Merge single-band files into multi-band COG |
28+
| `ddb sync` | Sync index with filesystem changes |
29+
| `ddb rescan` | Re-process all indexed files |
30+
| `ddb cog` | Build a Cloud Optimized GeoTIFF |
31+
| `ddb copc` | Build a Cloud Optimized Point Cloud |
32+
33+
## Installation
34+
35+
See the [CLI Installation](/docs/getting-started/installation#cli-installation) page for setup instructions.
36+
37+
## Examples
38+
39+
See [CLI Examples](/docs/cli/examples) for practical usage examples.
40+
41+
## Full Reference
42+
43+
See the [CLI Command Reference](/docs/cli/cli-reference) for the complete list of commands and options.

docs/building-from-source.md renamed to docs/contributing/building-from-source.md

File renamed without changes.

0 commit comments

Comments
 (0)