Getting started

Installation

Command line tool

Quick install

The release installer downloads the matching release bundle for the current platform, verifies its checksum, and installs a wrapper command.

Linux / macOSWindows

curl -fsSL https://github.com/3DBAG/geodepot/releases/latest/download/geodepot-install.sh | sh

Invoke-RestMethod https://github.com/3DBAG/geodepot/releases/latest/download/geodepot-install.ps1 | Invoke-Expression

The installers support installing a specific version as well.

Linux / macOSWindows

curl -fsSL https://github.com/3DBAG/geodepot/releases/latest/download/geodepot-install.sh | sh -s -- --version v1.0.3

$script = Invoke-RestMethod https://github.com/3DBAG/geodepot/releases/latest/download/geodepot-install.ps1
& ([scriptblock]::Create($script)) -Version v1.0.3

The default install locations are:

• Linux and macOS bundle: ~/.local/share/geodepot
• Linux and macOS wrapper: ~/.local/bin/geodepot
• Windows bundle: %LOCALAPPDATA%\geodepot
• Windows wrappers: %USERPROFILE%\.local\bin\geodepot.cmd and %USERPROFILE%\.local\bin\geodepot.ps1

The Windows installer updates the user PATH when needed. The POSIX installer prints the PATH change you need if ~/.local/bin is not already available in your shell.

Manual install

Download a release bundle from the latest release and extract it. Keep the extracted geodepot directory intact.

The release bundle contains two parts:

• a bundled runtime environment in env/
• a top-level launcher that activates that runtime and then starts Geodepot

The launcher names are:

• Linux and macOS: geodepot
• Windows: geodepot.cmd and geodepot.ps1

Typical extracted layout:

Linux / macOSWindows

geodepot/
├── geodepot
└── env/

geodepot/
├── geodepot.cmd
├── geodepot.ps1
└── env/

Run the top-level launcher, not the executable inside env/. The nested executable does not activate the bundled GDAL, PROJ, and PDAL environment on its own and may fail with missing proj.db or plugin lookup errors.

Linux / macOSWindows

cd geodepot
./geodepot --help

cd geodepot
.\geodepot.cmd --help

If you want to use Geodepot from any working directory, add the extracted geodepot directory itself to PATH. Do not copy or symlink the launcher to another directory, because it locates the bundled runtime relative to its own path.

Geodepot has complex dependencies, so do not pip install it, unless you are developing Geodepot itself. Use the provided binaries instead. For development, use pixi to create the environment and run the project tools.

API

C++PythonCMake

If you are using CMake, use FetchContent (or CPM) and link against geodepot.

Using CMake's FetchContent.

FetchContent_Declare(
  geodepot-api
  GIT_REPOSITORY https://github.com/3DBAG/geodepot-api.git
)
FetchContent_MakeAvailable(geodepot-api)

add_executable("test_integration" "test_integration.cpp")
target_link_libraries("test_integration" geodepot)

Using CPM.

CPMAddPackage("gh:3dbag/geodepot-api@1.0.4")

Use pixi or pip to build the Geodepot API and install the bindings.

git clone https://github.com/3DBAG/geodepot-api.git
cd geodepot-api
pixi run -e dev python -m pip install .

To add the Geodepot CMake functions to your current project, simply add the latest release of GeoDepot.cmake to your project's cmake directory, then include it. Make sure you include all modules from the cmake directory.

include(GeoDepot)

First time setup

Configure your user

The user information helps to identify changes and locks when working with a remote repository. It consists of a name and an e-mail address, and it is stored in the project repository.

geodepot config set user.name "My Name"
geodepot config set user.email "my@email.me"

Initialize a repository

A local Geodepot repository can be created empty, or from an existing remote repository.

Navigate to the project directory where you want to initialize a Geodepot repository. Normally, this would be the software project directory.

Create an empty repository.

geodepot init

Download and existing repository. Note that init does not download the data items, only the repository index. The data will be downloaded either by calling get the first time, or pull-ing the remote repository.

geodepot init https://data.3dgi.xyz/geodepot-test-data/mock_project/.geodepot

Manage test cases

Add data

The GeoPackage file path/to/local/wippolder.gpkg is added to the case wippolder with the name wippolder.gpkg, and the provided license and description are attached to the data entry. Geodepot tries to retrieve the Spatial Reference System (SRS) and extent from the data and add it to the data item.

geodepot add \
  --license CC0 \
  --description "A couple of buildings and a church in Delft for minimal testing." \
  wippolder \
  path/to/local/wippolder.gpkg

Update a data item

To update an existing data item, we use the add command without passing an input file.

geodepot add \
  --description "New description." \
  wippolder/wippolder.gpkg

View the repository contents

geodepot list prints the available cases and data items in the repository.

geodepot list

Returns:

wippolder
        /wippolder.gpkg
        /wippolder.las
        /wippolder.tif
3dbag
        /3dbag_one.city.json
tyler_debug
        /3dtiles

geodepot show prints the details of a case or data item.

geodepot show wippolder/wippolder.gpkg

Returns:

NAME=wippolder.gpkg

DESCRIPTION=New description.

format=GPKG
driver=None
license=CC0
sha1=b1ec6506eb7858b0667281580c4f5a5aff6894b2
changed_by=My Name <my@email.me>
extent=POLYGON ((85289.890625 447041.96875,85466.6953125 447041.96875,85466.6953125 447163.53125,85289.890625 447163.53125,85289.890625 447041.96875))
srs=PROJCS["Amersfoort / RD New",GEOGCS["Amersfoort",DATUM["Amersfoort",SPHEROID["Bessel 1841",6377397.155,299.1528128,AUTHORITY["EPSG","7004"]],AUTHORITY["EPSG","6289"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4289"]],PROJECTION["Oblique_Stereographic"],PARAMETER["latitude_of_origin",52.1561605555556],PARAMETER["central_meridian",5.38763888888889],PARAMETER["scale_factor",0.9999079],PARAMETER["false_easting",155000],PARAMETER["false_northing",463000],UNIT["metre",1,AUTHORITY["EPSG","9001"]],AXIS["Easting",EAST],AXIS["Northing",NORTH],AUTHORITY["EPSG","28992"]]

Collaboration

Multiple users can access the same test data by adding the same Geodepot repository on a remote server as a 'remote' to their local repository. The users have read/write access to the remote, so they can update the remote with their local changes.

When an empty repository is initialized, it does not reference any remotes. If you initialized the repository with a URL, the URL is added as a remote repository with the default name origin.

A remote is added with geodepot remote add.

geodepot remote add origin ssh://user@server:/path/to/.geodepot

The supported protocols are HTTP, HTTPS, SSH, SFTP. The pull and push commands only support the SSH and SFTP protocols.