titiler-multidim

Example of application built with titiler.xarray package

---

Source Code: https://github.com/developmentseed/titiler-multidim

---

Running Locally

# It's recommended to install dependencies in a virtual environment
uv sync --dev
export TEST_ENVIRONMENT=true  # set this when running locally to mock redis
#optional: Disable caching
#export TITILER_MULTIDIM_ENABLE_CACHE=false
uv run uvicorn titiler.multidim.main:app --reload

To access the docs, visit http://127.0.0.1:8000/api.html.

TiTiler 2 migration

TiTiler 2 is a breaking API upgrade:

• Use tilesize (pixels) instead of tile_scale; TileJSON defaults to tilesize=512, while the map viewer defaults to tilesize=256.
• Tile URLs no longer include an @{scale}x suffix.
• Set a selector method on the selector itself, for example sel=time=nearest::2020-01-06, instead of using sel_method.
• TileJSON now includes additional raster metadata fields.

Development

Tests use data generated locally by using tests/fixtures/generate_test_*.py scripts.

Install the package using uv with all development dependencies:

uv sync
uv run pre-commit install

To run all the tests:

uv run pytest

To run just one test:

uv run pytest tests/test_app.py::test_get_info 

VEDA Deployment

• Production deployments are handled in the NASA-IMPACT/veda-deploy repository.
• Test/dev stack deployments can be triggered by applying the deploy-dev label to a pull request in this repository. Each deployment requests a tile from the public native MUR, virtual MUR, and virtual NLDAS Icechunk stores.
• CDK synth checks run automatically on pull requests, including pull requests from forks. The filter fails closed: only pull requests limited to documentation, tests, markdown, and unrelated workflows report the check as skipped (which still satisfies the required status check on main); anything else — including application source, which the CDK app imports and the Lambda image bundles — runs the full check. The check is fully anonymous: cdk synth runs with dummy configuration (no VPC_ID, so the stack is environment-agnostic, and a dummy reader role ARN that is parsed but never resolved) and no AWS credentials, validating the synthesized template and Lambda asset sizes without access to any AWS account.

To run the same deployment smoke test manually:

uv run python scripts/test_deployment.py --api-url https://your-api.execute-api.us-west-2.amazonaws.com

The RASI historical Icechunk store is intentionally excluded because its source data are corrupted.

New Deployments

The following steps detail how to to setup and deploy the CDK stack from your local machine.

1. Install CDK and connect to your AWS account. This step is only necessary once per AWS account.

   # Download titiler repo
   git clone https://github.com/developmentseed/titiler-multidim.git
   
   # Install with the deployment dependencies
   uv sync --group deployment
   
   # Install the pinned local CDK CLI
   uv run npm --prefix infrastructure/aws ci
   
   # Deploys the CDK toolkit stack into an AWS environment
   uv run npm --prefix infrastructure/aws run cdk -- bootstrap
   
   # or to a specific region and or using AWS profile
   AWS_DEFAULT_REGION=us-west-2 AWS_REGION=us-west-2 AWS_PROFILE=myprofile uv run npm --prefix infrastructure/aws run cdk -- bootstrap

2. Update settings

   Set environment variable or hard code in infrastructure/aws/.env file (e.g STACK_STAGE=testing).

3. Pre-Generate CFN template

   uv run npm --prefix infrastructure/aws run cdk -- synth  # Synthesizes and prints the CloudFormation template for this stack

4. Deploy

   STACK_STAGE=staging uv run npm --prefix infrastructure/aws run cdk -- deploy titiler-xarray-staging
   
   # Deploy in specific region
   AWS_DEFAULT_REGION=us-west-2 AWS_REGION=us-west-2 AWS_PROFILE=smce-veda STACK_STAGE=production  uv run npm --prefix infrastructure/aws run cdk -- deploy titiler-xarray-production

Important

The Python aws-cdk-lib dependency in pyproject.toml is the construct library used by infrastructure/aws/cdk/app.py. The npm aws-cdk dependency in infrastructure/aws/package.json provides the cdk CLI. Keep the Python library pinned in pyproject.toml, keep the CLI pinned in package.json and package-lock.json, and always invoke CDK through npm --prefix infrastructure/aws run cdk -- ... so synth and deploy use the same local CLI version.

In AWS Lambda environment we need to have specific version of botocore, S3FS, FSPEC and other libraries. To make sure the application will both work locally and in AWS Lambda environment you can install the dependencies using python -m pip install -r infrastructure/aws/requirement-lambda.txt