Skip to main content

CLI

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

Installation

C:\> ddb --version
1.0.6 (git commit 1952a82)

Examples

You can do all sort operations with ddb. We recommend to check out the list of commands:

Sharing datasets

From a directory with images, simply type:

ddb share *.JPG
tip

By default the images are shared with Hub. You will need to register an account to get a username and password. But you can also self-host your own Registry.

You can select a different server by typing:

ddb share *.JPG -s http://localhost:5000
--> https://localhost:5000/r/admin/193514313aba4949ab5578b28ba1dd5b

Because we didn't set a tag, ddb generated a random one for you. You can change the tag by visiting the URL. You can also explicitly set a tag, like so:

ddb share *.JPG -t pierotofy/brighton

Or if you're running your own Registry:

ddb share *.JPG -t http://localhost:5000/admin/brighton

Tags are defined as:

[server]/organization/dataset

With the server component being optional.

Editing datasets

Using the Web UI provided by Registry is the easiest way to make changes.

You can also clone (download) an existing dataset from a Registry for offline use, make modifications, then sync back your changes.

Let's use this dataset: https://hub.dronedb.app/r/pierotofy/brighton-beach

You can clone it via:

ddb clone pierotofy/brighton-beach

Let's add a README.md file that describes the dataset. Create a README.md file using Markdown syntax and save it in the brighton-beach directory. Afterwards:

cd brighton-beach/
ddb add README.md

Great! We are now ready to push the changes.

ddb push

Uuups! This will trigger an error, since we don't have permission to make modifications to this dataset (it belongs to pierotofy). Let's make our own copy to a different Registry server and user:

ddb tag http://localhost:5000/admin/brighton-copy
ddb push

Metadata Entries

DroneDB supports the addition of metadata to any file or directory within the index. This can be used to store information of any kind in JSON format:

ddb meta set pilot '{"name": "John Smith"}'
ddb meta get pilot --format json
--> {"data":{"name":"John S."},"id":"ff4f0f26-8741-4423-bde5-b445750937bb","mtime":1640985850}

ddb add photo.JPG
ddb meta add comments '{"text": "Nice one!", "author": "John S."}' -p photo.JPG
ddb meta get comments -p photo.JPG --format json
--> [{"data":{"author":"John S.","text":"Nice one!"},"id":"550d0b5c-108b-4996-b7e8-467b4cb87937","mtime":1640986217}]

Singular and plural metadata keys are supported. Plural keys (ending with s) are treated as lists, whereas singular keys are objects.

Metadata entries are synced on push/pull and people working on the same dataset while offline can later sync back online without conflicts.

Projecting images

geoproject

You can project images onto a map.

ddb geoproj images/DJI_0018.JPG -o projected/

Creating static tiles (XYZ/TMS)

DroneDB can create static tiles for GeoTIFFs, drone images and EPT. It's similar to gdal2tiles.py, but it's a bit faster and can handle more formats. You can use these tiles in applications such as Leaflet or OpenLayers to display them on the web.

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

Extracting GPS locations/footprints to GeoJSON

You can quickly extract the locations of images to GeoJSON via:

ddb info *.JPG -f geojson -o gps.geojson

Or for image footprints:

ddb info *.JPG -f geojson --geometry polygon -o footprint.geojson

This works with orthophotos, elevation models and point clouds as well!

ddb info point_cloud.laz -f geojson --geometry polygon -o footprint.geojson

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

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

chattr

Manage database attributes

Attributes:
public mark database as publicly accessible


Usage:
ddb chattr [+-attribute] [args]

-w, --working-dir arg Working directory (default: .)
-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

ept

Build an EPT index from point cloud files.

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

-o, --output arg Output directory where to store EPT data
-i, --input arg File(s) to process
-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

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

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

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 EPT

Usage:
ddb tile [geo.tif | image.jpg | ept.json | https://host.com/cog.tif | https://host.com/image.jpg | https://host.com/ept.json] [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