Moving Files In and Out of AO

AO gives you five ways to move files in and out, from a single click in the browser to unattended and server-to-server transfers. There are also ways to share data without moving it at all. Your files keep their original formats the whole way, so whatever you put into AO, you can take out exactly as it was.

This page helps you pick the right option for the job.

Quick guide

Options at a glance

AO web app

Upload: in a project's Files tab, choose Upload. Add files, or whole folders by drag-and-drop or Browse folders, and AO keeps the folder structure. AO uploads up to four files at a time. It skips files it already has (same name, folder and content) and asks what to do about name conflicts: Keep Both, Skip, Replace or Stop, with Apply to all conflicts when several files conflict. For many small files, upload a ZIP with Unzip Archives checked. AO extracts it on the server, and extraction carries on even if you close the tab.

Download: select files or folders (a folder includes everything inside it) and choose Download. A single file downloads directly. For several files, AO builds one ZIP on the server, and the download starts once the ZIP is complete.

Good to know:

• Each file uploads in one piece. If the connection drops, that file starts again from the beginning.
• Self-hosted AO and AO OnBoard take files up to 100 GB each.
• Very large single files can show an upload error even though the upload completes. Refresh the Files tab before retrying.
• Extracting a ZIP replaces files with the same name in the same folder.
• There is no progress bar while AO builds a ZIP, and the page stops waiting after an hour. Keep ZIP downloads to a few GB. Don't click Download again while a ZIP is being prepared, because that can produce an incomplete ZIP. For anything bigger, use the AO CLI.
• In projects backed by a cloud mount, download one file at a time.
• Visualizations can't be downloaded from the Files tab. Download their source files instead.

AO CLI

The AO CLI is a command-line program that uploads a folder on your computer to an AO project, or downloads a project's files into a folder. It's the best choice for large transfers: it moves files one by one with no ZIP step, runs up to 10 transfers at once, can run unattended, and a second run transfers only what's missing. Download it from the AO Tools project in AO; if you don't see that project, contact support@terradepth.com. For setup, options and troubleshooting, see AO CLI.

Cloud mounts

Cloud mounts connect AO to storage you already use:

• Amazon S3 and S3-compatible storage (such as MinIO)
• Azure Blob Storage
• Google Cloud Storage and Google Drive
• SFTP and FTP
• SMB (Windows and NAS shares)
• another AO

Terradepth support adds the mount for your organization (see Add a cloud mount); then an Admin attaches it to a project. Professionals and Admins can then use the Files tab to copy or move files between AO projects and the mounted storage, browse it, or visualize a file straight from it. The data moves from AO's servers directly to your storage, not through your computer.

Good to know:

• Copies work on files, not folders. Select all the files in a folder to copy them together, and do subfolders one at a time.
• Files copy one after another while the page is open, with a spinner instead of per-file progress. Keep the page open until it finishes.
• AO won't overwrite a file that already exists at the destination. Rename or remove it first.
• A single file copy that runs longer than about two hours can time out. Use the AO CLI for very large files.
• To visualize a file from mounted storage, AO copies it in to render it.
• A project backed by a cloud mount already keeps its files in your storage.

Remote Sync

Remote Sync copies projects from one AO to another, for example from AO OnBoard on a vessel to AO in the cloud. It moves the files with their folder structure, plus objects and finished visualizations, so the project arrives ready to use. Click your initial in the top right corner and choose Remote Sync, sign in to the other AO, pick the projects and start. The transfer runs as a background job on the sending AO, with progress, status and a transfer report.

Good to know:

• Remote Sync needs the Professional or Admin role.
• The sending AO must be able to reach the receiving AO's address. Use an https:// address: an http:// address also works, but the transfer isn't encrypted. Only the sender initiates connections.
• If the destination already has a project with the same name, AO adds to it. Files that already match are skipped. Files with the same name but different content are replaced.
• If a transfer is interrupted or only partly completes, choose Copy Again. It skips everything already transferred, and an interrupted file starts again from the beginning.
• Each AO runs one transfer at a time. Others wait in the queue.
• Files of 11 GB or more get a single attempt. If one fails, move it with the AO CLI.

REST API

The web app and the CLI both use AO's REST API, and your own scripts and systems can too. Sign in with POST /api/v1/users/login, sending your email and password in the X-Email and X-Password headers. The response's user-context header holds an auth_token, which you send as a bearer token, and a refresh_token: when the bearer token expires, send the refresh token in the X-Refresh-Token header to POST /api/v1/users/refresh-token for a new one. See Getting started with the AO API.

Good to know:

• Downloading file by file avoids ZIP size concerns. The ZIP endpoint has the same limits as ZIP downloads in the web app.
• Each upload is a single request. Chunked, resumable upload isn't available.
• AO checks each upload against the SHA-256 you declare, so a corrupted upload is rejected rather than stored.
• Run a handful of transfers in parallel. The CLI uses five by default.
• The full API reference is at https://<your AO address>/api/v1/docs/. See Getting started with the AO API, and Upload and download files with a script for a ready-made Python script.

Sharing without moving files

• Layer links: in the Layers window, choose Copy shared-layer definition. You get standard tile URLs (TMS, XYZ, 3D Tiles or terrain, depending on the visualization) that GIS tools and 3D viewers can load. The links serve the rendered layer, not the source files, and anyone who has a link can view the layer.
• External layers: add WMS, WMTS, XYZ, TMS, 3D Tiles or terrain services to AO by URL to view them alongside your data, with nothing copied into AO.
• Reports and exports: the Files tab's Report exports a CSV inventory of a project's files (path, name and size), a project's Objects tab exports objects as CSV, and Mission Planner exports missions as .tdm files. See Reports and exports.

Large exports

For a full export of one or more projects to a disk or server you control:

1. Take an inventory. In each project's Files tab, use Report to save a CSV of every file and its size.
2. Download with the AO CLI. Make one folder per project, each with its own settings.json (an absolute Directory and "OnConflict": "OVERWRITE", so a re-run replaces any partial copy with AO's file), then run aocli file down --threads 8 --yes.
3. Re-run until clean. Run the same command until it finishes without failures. Each re-run skips files that are already in place with a matching SHA-256.
4. Check against the inventory. File count and total size should match the report. On a final re-run, every file should be reported as already present. If the CLI reports skipped conflicts, the export isn't complete.

Depending on the destination:

• Your cloud or NAS: run the CLI on a machine that writes to that storage, or use a cloud mount for a modest number of files.
• Your own AO: use Remote Sync, which brings visualizations and objects along too.

Open by design

AO stores your files exactly as you uploaded them, in their original formats, and verifies uploads with SHA-256 checksums. Every option on this page uses open standards: HTTPS and REST, S3, SFTP, FTP, SMB and standard tile formats. The AO web app, AO CLI, REST API and cloud mounts to storage on your network also work on private and air-gapped networks. Remote Sync needs internet access from the browser you start it in. Your data is never locked in.

For what's planned, see Coming soon in AO.

Availability: Remote Sync and Mission Planner are turned on per organization. To use them, contact support@terradepth.com.

Related: AO CLI · Connecting AO to other data · Best practices for loading data to AO