Reference

ddb is a command line interface (CLI) to access DroneDB's functions. This makes it ideal for power users and for creating automated workflows.

See the CLI Overview page for a quick command summary and links to tutorials.

Quick Examples

Below are concise examples for commands not covered in the Examples page.

Projecting images

Project images onto a georeferenced map:

ddb geoproj images/DJI_0018.JPG -o projected/

Creating static tiles (XYZ/TMS)

Generate tiles for GeoTIFFs, drone images and COPC point clouds. Similar to gdal2tiles.py but faster and with more format support:

ddb tile DJI_0018.JPG output_tiles/
ddb tile orthophoto.tif output_tiles/

Building COPC point clouds

Build COPC (Cloud Optimized Point Cloud) files for efficient streaming:

ddb copc output/ point_cloud.laz

Supported input formats: LAS, LAZ, E57, PTS, XYZ, PLY.

Generating Cloud Optimized GeoTIFFs (COG)

Convert standard GeoTIFFs to COGs for efficient streaming with range requests:

ddb cog output.tif input.tif

Extracting GPS locations/footprints to GeoJSON

# GPS points
ddb info *.JPG -f geojson -o gps.geojson

# Image footprints (polygons)
ddb info *.JPG -f geojson --geometry polygon -o footprint.geojson

Generating STAC Catalogs

Generate STAC-compliant JSON for interoperability:

cd my-dataset/
ddb stac

# For a specific file
ddb stac -p orthophoto.tif

Building 3D Model Tiles

Generate Nexus files for efficient web streaming of 3D meshes:

ddb nxs model.obj output.nxz

Supported input formats: OBJ, GLTF, GLB.

Generate OGC 3D Tiles (tileset.json + b3dm) for the unified 3D viewer (requires the optional Obj2Tiles binary):

ddb 3dtiles model.obj ./3dtiles

# Force a local (non-georeferenced) tileset
ddb 3dtiles model.obj ./3dtiles --local

# Explicit WGS84 origin
ddb 3dtiles model.obj ./3dtiles --lat 43.7 --lon 10.4 --alt 50

Generating Thumbnails

ddb thumbs *.JPG -o thumbs/
ddb thumbs orthophoto.tif -o thumb.jpg -s 1024

Re-processing indexed files after an upgrade

When you upgrade DroneDB to a version that extracts additional metadata or supports new file types, use rescan to update all metadata in place:

cd my-dataset/
ddb rescan

# Only specific types
ddb rescan --type image,pointcloud

# Continue even if some files fail
ddb rescan --continue-on-error

Environment Variables

tip

For practical workflow examples (multispectral, terrain analytics, clone/push, metadata), see the Examples page.

DroneDB reads the following environment variables at runtime. Variables marked GDAL config can also be set via CPLSetConfigOption() in the GDAL C API.

General

Variable	Description
DDB_LOG	If set (any value), enables logging to file (ddb-log.csv) in the current directory.
DDB_DEBUG	If set (any value), enables verbose debug output on the console. Equivalent to passing --debug.
DDB_HOME	Override the DDB home directory (default: ~/.ddb). Stores credentials and user profile.
DDB_DATA	Override the DDB data directory used for bundled data files (timezone database, etc.).

Point Cloud (COPC)

Variable	Description
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.
DDB_USE_PDAL_COPC	Set to 1 to force the PDAL COPC backend, bypassing Untwine.
DDB_COPC_BACKEND	Explicit backend selection: "untwine", "pdal", or "auto" (default). Unknown values are silently ignored. DDB_USE_PDAL_COPC=1 takes precedence.

COG Build (GDAL config)

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.

Variable	Default	Description
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.
DDB_WARP_MEMORY_MB	512	GDALWarp memory buffer size in MB (-wm flag). Larger values reduce chunking overhead when multi-threading is active.
DDB_COG_CACHE_MB	1024	GDAL block cache size in MB during COG build. Raised temporarily before the warp and restored afterwards.

Gaussian Splats

Variable	Default	Description
DDB_GSPLAT_SH_BITS	SPZ defaults	Override spherical-harmonics bit depth for SPZ packing. One value (5) sets sh1Bits; two comma-separated values (5,4) set sh1Bits and shRestBits. Each value must be between 1 and 8.

Commands Reference

add

Add files and directories to an index.

Usage:
  ddb add *.JPG [args] [PATHS]

  -w, --working-dir arg  Working directory (default: .)
  -r, --recursive        Recursively add subdirectories and files
  -p, --paths arg        Paths to add to index (files or directories)
  -h, --help             Print help
      --debug            Show debug output

align

Align a GeoTIFF (ortho or DEM) to a reference GeoTIFF, correcting georeferencing offset.

Usage:
  ddb align -i source.tif -r reference.tif -o aligned.tif

  -i, --input arg      Source GeoTIFF to align
  -r, --reference arg  Reference GeoTIFF (ground truth, more accurate)
  -o, --output arg     Output aligned GeoTIFF (COG, reprojected to EPSG:3857)
  -m, --mode arg       similarity (default) | translation (default: similarity)
      --validate       Only validate inputs; do not align
      --no-seed        Disable phase-correlation seed (slower NCC search)
  -h, --help           Print help
      --debug          Show debug output

build

Build DroneDB files for efficient streaming over a network.

Usage:
  ddb build [-p path/to/file.laz] [--output out_dir] [args]

  -o, --output arg       Output folder (default: .ddb/build)
  -p, --path arg         File to process
  -w, --working-dir arg  Working directory (default: .)
  -f, --force            Force rebuild
  -h, --help             Print help
      --debug            Show debug output

clone

Clone a repository into a new directory

Clones a repository into a newly created directory.

Usage:
  ddb clone (tag|url) folder [args]

  -t, --target arg  Repository tag or full url
  -f, --folder arg  Target folder (default: )
  -h, --help        Print help
      --debug       Show debug output

cog

Build a Cloud Optimized GeoTIFF from an existing GeoTIFF.

Usage:
  ddb cog cog.tif input.tif [args]

  -o, --output arg  Output Cloud Optimized GeoTIFF
  -i, --input arg   Input GeoTIFF to process
  -h, --help        Print help
      --debug       Show debug output

delta

Generate delta between two ddb databases

Outputs the delta that applied to target turns it into source

Usage:
  ddb delta source target [args]

  -s, --source arg  Source ddb
  -t, --target arg  Target ddb (default: .)
  -f, --format arg  Output format (text|json) (default: text)
  -h, --help        Print help
      --debug       Show debug output

cleanup

Remove stale database entries and orphaned build artifacts from a dataset.

Usage:
  ddb cleanup [args]

  -w, --working-dir arg  Working directory (default: .)
  -h, --help             Print help
      --debug            Show debug output

copc

Build a COPC (Cloud Optimized Point Cloud) file from point cloud files.

Usage:
  ddb copc outdir/ *.las [args]

  -o, --output arg  Output directory where to store the COPC file (cloud.copc.laz)
  -i, --input arg   File(s) to process
  -h, --help        Print help
      --debug       Show debug output

contour

Generate contour lines (GeoJSON) from a DEM/DSM/DTM raster.

Usage:
  ddb contour [options] input.tif [args]

      --input arg     Input single-band raster (DEM/DSM/DTM)
  -o, --output arg    Output GeoJSON file (default: stdout)
  -i, --interval arg  Vertical interval between contour levels (raster units) (default: 0)
  -n, --count arg     Target number of contour levels (used when --interval is 0) (default: 0)
  -b, --base arg      Reference base elevation (default: 0)
      --min arg       Drop contours below this elevation (default: nan)
      --max arg       Drop contours above this elevation (default: nan)
  -s, --simplify arg  Geometry simplification tolerance (raster CRS units) (default: 0)
      --band arg      1-based raster band index (default: 1)
  -h, --help          Print help
      --debug         Show debug output

geoproj

Project images to georeferenced rasters

Usage:
  ddb geoproj output/ *.JPG [args]

  -o, --output arg  Output path (file or directory)
  -i, --images arg  Images to project
  -s, --size arg    Output image size (size[%]|0) (default: 100%)
  -h, --help        Print help
      --debug       Show debug output

info

Retrieve information about files and directories

Usage:
  ddb info *.JPG [args]

  -i, --input arg     File(s) to examine
  -o, --output arg    Output file to write results to (default: stdout)
  -f, --format arg    Output format (text|json|geojson) (default: text)
  -r, --recursive     Recursively search in subdirectories
  -d, --depth arg     Max recursion depth (default: 0)
      --geometry arg  Geometry to output (for geojson format only)
                      (auto|point|polygon) (default: auto)
      --with-hash     Compute SHA256 hashes
  -h, --help          Print help
      --debug         Show debug output

init

Initialize an index. If a directory is not specified, initializes the index in the current directory

Usage:
  ddb init [args] [DIRECTORY]

  -w, --working-dir arg  Working directory (default: .)
      --from-scratch     Create the index database from scratch instead of
                         using a prebuilt one (slower)
  -h, --help             Print help
      --debug            Show debug output

list

List indexed files and directories

Usage:
  ddb list *.JPG [args]

  -i, --input arg        File(s) to list
  -o, --output arg       Output file to write results to (default: stdout)
  -w, --working-dir arg  Working directory (default: .)
  -r, --recursive        Recursively search in subdirectories
  -d, --depth arg        Max recursion depth (default: 0)
  -f, --format arg       Output format (text|json) (default: text)
  -h, --help             Print help
      --debug            Show debug output

mask

Mask orthophoto borders making them transparent.

Usage:
  ddb mask input.tif [-o output.tif] [-n 15] [-w] [-c r,g,b]

  -i, --input arg   Input GeoTIFF file
  -o, --output arg  Output GeoTIFF file (default: <input>_masked.tif)
  -n, --near arg    Tolerance in grey levels (default: 15)
  -w, --white       Search for white borders instead of black
  -c, --color arg   Custom color r,g,b (e.g. 0,0,0)
  -h, --help        Print help
      --debug       Show debug output

login

Authenticate with a registry.

Usage:
  ddb login [args]

      --server arg    Registry server to authenticate to (default:
                      hub.dronedb.app)
  -u, --username arg  Username
  -p, --password arg  Password
  -h, --help          Print help
      --debug         Show debug output

logout

Logout from all registries. To logout from a single registry, use the --server option.

Usage:
  ddb logout [args]

      --server arg  Registry server to logout from (default: hub.dronedb.app)
  -h, --help        Print help
      --debug       Show debug output

meta

Manage database metadata

Usage:
  ddb meta [add|set|rm|get|unset|ls|dump|restore] [key|ID] [data] [-p path] [args]

  -c, --command arg      Command
  -k, --key arg          Metadata key/ID (default: )
  -p, --path arg         Path to associate metadata with (default: )
  -d, --data arg         Data string|number|JSON to set (default: )
  -w, --working-dir arg  Working directory (default: .)
  -f, --format arg       Output format (text|json) (default: text)
  -h, --help             Print help
      --debug            Show debug output

merge-multispectral

Merge single-band raster files into a multi-band GeoTIFF.

Usage:
  ddb merge-multispectral -o output.tif band1.tif band2.tif ...

  -o, --output arg  Output Cloud Optimized GeoTIFF path
      --validate    Only validate inputs, don't merge
  -i, --input arg   Input single-band raster files
  -h, --help        Print help
      --debug       Show debug output

nxs

Generate nexus (NXS/NXZ) files from OBJs.

Usage:
  ddb nxs model.obj [output.nxz|output.nxs] [args]

  -i, --input arg   File to process
  -o, --output arg  Nexus output file
      --overwrite   Overwrite output file if it exists
  -h, --help        Print help
      --debug       Show debug output

password

Manage database passwords

Usage:
  ddb password [a,append|v,verify|c,clear] [password] [args]

  -w, --working-dir arg  Working directory (default: .)
  -c, --command arg      Command to execute
  -a, --argument arg     Command argument (default: )
  -h, --help             Print help
      --debug            Show debug output

pull

Pulls changes from a remote repository.

Usage:
  ddb pull

  -r, --remote arg   The remote Registry (default: )
  -t, --keep-theirs  Keep changes from remote registry and override local
                     ones
  -o, --keep-ours    Keep local changes override remote ones
  -h, --help         Print help
      --debug        Show debug output

push

Pushes changes to a remote repository.

Usage:
  ddb push [remote] [args]

  -r, --remote arg  The remote Registry (default: )
  -h, --help        Print help
      --debug       Show debug output

remove

Remove files and directories from an index. The filesystem is left unchanged (actual files and directories will not be removed)

Usage:
  ddb rm image1.JPG image2.JPG [...] [args] [PATHS]

  -w, --working-dir arg  Working directory (default: .)
  -p, --paths arg        Paths to remove from index (files or directories)
  -h, --help             Print help
      --debug            Show debug output

rescan

Re-process all indexed files to update metadata.
Useful when upgrading DroneDB to a version that extracts more metadata
or supports new file types.

Usage:
  ddb rescan [args]

  -w, --working-dir arg  Working directory (default: .)
  -t, --type arg         Entry types to rescan (comma-separated).
                         Valid types: generic, geoimage, georaster,
                         pointcloud, image, dronedb, markdown, video,
                         geovideo, model, panorama, geopanorama, vector
      --continue-on-error  Continue processing if an error occurs
  -h, --help             Print help
      --debug            Show debug output

search

Search indexed files and directories

Usage:
  ddb search '*file*' [args]

  -q, --query arg        Search query
  -w, --working-dir arg  Working directory (default: .)
  -f, --format arg       Output format (text|json) (default: text)
  -h, --help             Print help
      --debug            Show debug output

setexif

Modify EXIF values in files.

Usage:
  ddb setexif *.JPG [args]

  -i, --input arg    File(s) to modify
      --gps-alt arg  Set GPS Altitude (decimal degrees)
      --gps-lon arg  Set GPS Longitude (decimal degrees)
      --gps-lat arg  Set GPS Latitude (decimal degrees)
      --gps arg      Set GPS Latitude,Longitude,Altitude (decimal degrees,
                     comma separated)
  -h, --help         Print help
      --debug        Show debug output

share

Share files and folders to a registry

Usage:
  ddb share *.JPG [args]

  -i, --input arg     Files and directories to share
  -r, --recursive     Recursively share subdirectories
  -t, --tag arg       Tag to use (organization/dataset or
                      server[:port]/organization/dataset) (default: hub.dronedb.app//)
  -p, --password arg  Optional password to protect dataset (default: )
  -s, --server arg    Registry server to share dataset with (alias of: -t
                      <server>//)
  -q, --quiet         Do not display progress
  -h, --help          Print help
      --debug         Show debug output

stac

Generate STAC catalogs

Usage:
  ddb stac

  -w, --working-dir arg         Working directory (default: .)
  -p, --path arg                Entry path to generate a STAC item for (which
                                must be part of the DroneDB index) (default:
                                )
      --stac-catalog-root arg   STAC Catalog absolute URL (default: )
      --stac-collection-root arg
                                STAC Collection absolute URL (default: .)
      --id arg                  Set STAC id explicitely instead of using the
                                directory name (default: )
  -h, --help                    Print help
      --debug                   Show debug output

stamp

Generate a stamp of the current index.

Usage:
  ddb stamp

  -w, --working-dir arg  Working directory (default: .)
  -f, --format arg       Output format (text|json) (default: text)
  -h, --help             Print help
      --debug            Show debug output

status

Show files and directories index status compared to the filesystem

Usage:
  ddb status [directory] [args]

  -w, --working-dir arg  Working directory (default: .)
  -h, --help             Print help
      --debug            Show debug output

sync

Sync files and directories in the index with changes from the filesystem

Usage:
  ddb sync

  -w, --working-dir arg  Working directory (default: .)
  -h, --help             Print help
      --debug            Show debug output

system

Manage ddb

Commands:
	clean	Cleanup user cache files


Usage:
  ddb system COMMAND

  -c, --command arg  Command (default: )
  -h, --help         Print help
      --debug        Show debug output

tag

Gets or sets the dataset tag.

Usage:
  ddb tag [tag] [args]

  -t, --tag arg  New tag (default: )
  -h, --help     Print help
      --debug    Show debug output

thumbs

Generate thumbnails for images and rasters

Usage:
  ddb thumbs [image.tif | *.JPG] -o [thumb.jpg | output/] [args]

  -i, --input arg   File(s) to process
  -o, --output arg  Output file or directory where to store thumbnail(s)
  -s, --size arg    Size of the largest side of the images (default: 512)
      --use-crc     Use CRC for output filenames
  -h, --help        Print help
      --debug       Show debug output

tile

Generate tiles for GeoTIFFs, GeoImages and COPC

Usage:
  ddb tile [geo.tif | image.jpg | cloud.copc.laz | https://host.com/cog.tif | https://host.com/image.jpg | https://host.com/cloud.copc.laz] [output directory] [args]

  -i, --input arg   Path or URL to file to tile
  -o, --output arg  Output directory where to store tiles (default:
                    {filename}_tiles/)
  -f, --format arg  Output format (text|json) (default: text)
  -z, arg           Zoom levels, either a single zoom level "N" or a range
                    "min-max" or "auto" to generate all zoom levels (default:
                    auto)
  -x, arg           Generate a single tile with the specified coordinate
                    (XYZ, unless --tms is used). Must be used with -y (default:
                    auto)
  -y, arg           Generate a single tile with the specified coordinate
                    (XYZ, unless --tms is used). Must be used with -x (default:
                    auto)
  -s, --size arg    Tile size (default: 256)
      --tms         Generate TMS tiles instead of XYZ
  -h, --help        Print help
      --debug       Show debug output

3dtiles

Generate OGC 3D Tiles (tileset.json + b3dm) from OBJs using Obj2Tiles.

Usage:
  ddb 3dtiles model.obj [output_dir]

  -i, --input arg    Model to process (OBJ/GLTF/GLB)
  -o, --output arg   Output 3D Tiles directory (defaults to a 3dtiles/ folder next to the input)
      --lat arg      Latitude of the model origin (WGS84). With --lon, forces a georeferenced tileset
      --lon arg      Longitude of the model origin (WGS84). With --lat, forces a georeferenced tileset
      --alt arg      Altitude of the model origin in meters (used with --lat/--lon) (default: 0)
      --local        Force a non-georeferenced (local) tileset, skipping sidecar auto-detection (default: false)
      --overwrite    Overwrite the output directory if it exists (default: false)
  -h, --help         Print help
      --debug        Show debug output

gsplat

Convert a Gaussian Splat (.ply/.splat/.spz) to the compressed .spz format.

Usage:
  ddb gsplat input.{ply|splat|spz} [output.spz]

  -i, --input arg   Gaussian Splat file to convert (.ply, .splat or .spz)
  -o, --output arg  Output .spz file
  -h, --help        Print help
      --debug       Show debug output