Raster & Vector Export
Technical Documentation

1. Scope

Two export tools are provided through the Analysis Server: Raster Export for raster project layers and Vector Export for PostGIS-backed vector layers. Both tools are available as analysis jobs and return a downloadable artifact or direct object URL.

2. Core Principles

• Backward compatible: existing layer, commit and project-revision behavior is not changed.
• Download-only: no new public.layers row for an export result.
• No new commit: no gc_commit should be created only because a file was exported.
• No new project revision: export should reference the current revision/history context rather than generate a new one.
• Direct when possible: avoid re-encoding raster data if the existing object already satisfies the request.
• Transform only when necessary: reprojection/resampling/conversion is executed only if the selected output requires it.
• Large-data aware: do not proxy multi-GB files through FastAPI when a secure presigned object URL can be used.
• Explicit format semantics: GeoJSON, KML, DXF, GPKG, SHP, TIFF and ECW have different CRS/metadata capabilities.

3. High-Level Architecture

3.1 Main analysis identifiers

4. Export Audit & Project History

Export is a project activity, but not a data mutation. The history system should therefore link the export to the current project revision / latest commit context without creating a new revision.

4.1 Recommended audit fields

• owner_id
• operator_id
• project_id
• layer_id / source raster reference
• analysis_id
• source revision / latest existing commit
• output format
• target CRS
• target resolution where applicable
• artifact path/object key or direct-source reference
• created/completed/downloaded timestamps
• status and error information

5. Raster Export

Raster Export supports two fundamentally different execution modes: direct object delivery and generated export. The worker decides which path is valid from the requested format, CRS and target resolution.

6. Raster Export Parameters

7. Direct TIFF Export

7.1 When direct export is allowed

Direct delivery is used only when all conditions are satisfied:

• Output format = TIFF.
• No CRS transformation is required.
• target_resolution = 0 / Auto.
• The source object is already a suitable downloadable raster/COG.

7.2 Why this is preferred

• avoids unnecessary CPU and disk I/O;
• avoids recompressing a valid COG;
• preserves original raster exactly;
• works well for very large imagery;
• reduces temporary storage pressure on the Analysis Server.

8. TIFF Export with Reprojection / Resampling

If the user requests a different CRS or an explicit non-zero target resolution, the raster must be transformed locally/temporarily before download.

8.1 Resampling guidance

8.2 COG output

Transformed TIFF should preferably be emitted as a valid Cloud Optimized GeoTIFF with suitable tiling, compression and overviews. The export artifact itself does not need to be inserted as a new project layer.

9. ECW Export

ECW is always a generated export because the existing project object is normally TIFF/COG. Reprojection and resolution change can be combined with conversion in the same export flow.

9.1 Driver requirement

ECW writing requires a GDAL build with a writable ECW driver. The worker must test driver capability and return a clear error when unsupported.

gdalinfo --formats | grep -i ECW

10. Raster Download URL Strategy

For direct S3 raster delivery, use a virtual-hosted presigned URL compatible with the object-storage TLS certificate. This avoids SSL hostname mismatch problems that may occur with an incompatible path-style endpoint.

10.1 Preferred browser flow

10.2 Why 302 redirect

A browser-oriented download redirect is simpler and more compatible than proxying large objects through the API. The API keeps authorization/audit control, while S3/object storage handles the data transfer.

10.3 Filename handling

• Prevent duplicate extensions such as .tif.tif.
• Do not mutate the source key merely to achieve a desired download filename.
• Sanitize user-supplied names.

11. Raster Export Error Handling

12. Vector Export

Vector Export moves large-data conversion responsibility to the Analysis Server rather than the lightweight Vector Tile service. The source of truth is the project PostGIS spatial table referenced by public.layers.spatial_table.

13. Vector Export Parameters

14. GeoPackage Export

GeoPackage is the preferred general-purpose vector export because it is a single file, supports standard CRS metadata, long field names, multiple geometry types/tables, and avoids Shapefile sidecar limitations.

ogr2ogr
-f GPKG
output.gpkg
PG:"..."
source_table
-t_srs EPSG:xxxx

15. ESRI Shapefile ZIP Export

A Shapefile is actually a file set. The download artifact should therefore be a ZIP containing all required components.

export_name.zip
├─ export_name.shp
├─ export_name.shx
├─ export_name.dbf
├─ export_name.prj
└─ optional .cpg

15.1 Known Shapefile limitations

• field names are heavily constrained compared with modern formats;
• attribute types and text encoding are less expressive;
• one primary geometry type per dataset;
• large/complex modern datasets are better exported as GeoPackage.

16. GeoJSON Export

GeoJSON is useful for web interoperability and human-readable exchange. For standards-compliant modern GeoJSON, coordinates should normally be emitted in WGS84 longitude/latitude.

17. KML Export

KML uses geographic longitude/latitude coordinates and should be exported in WGS84. Therefore the export worker should force or transform KML output to EPSG:4326.

User-selected projected EPSG should not be silently written into KML as if KML were a generic projected-vector container.

18. DXF / CAD Export

DXF is intended for CAD interoperability. Geometry can be reprojected before export, but CRS metadata support is not equivalent to GIS formats such as GeoPackage.

18.1 Recommended behavior

• allow target EPSG transformation before writing;
• include CRS information in export metadata/audit;
• do not imply that the DXF file itself reliably carries full GIS CRS semantics;
• consider simplifying unsupported attribute structures if the driver requires it, with a visible warning.

19. Vector Export Engine

The preferred conversion path is direct PostGIS → GDAL/OGR output. Avoid loading an entire large layer into GeoPandas unless a specific transformation requires it.

19.1 Why direct ogr2ogr

• streams records instead of duplicating the whole layer in application RAM;
• uses mature GDAL/OGR drivers;
• supports server-side SQL and CRS transformation;
• handles large datasets more predictably;
• keeps export work away from the Vector Tile API.

19.2 Source table resolution

data_asset.layer_id
      ↓
public.layers.id
      ↓
public.layers.spatial_table
      ↓
owner PostGIS spatial table

The physical vector table name belongs in public.layers.spatial_table; it does not need to be duplicated into data_asset.

20. Analysis Worker Integration

The active Analysis Server worker must recognize output_kind="export". The export branch should be handled centrally by the worker, just like vector/raster/model branches.

20.1 Worker enable flag

The runtime flag ANALYSIS_WORKER_ENABLED should actually control whether the Analysis Server claims analysis jobs. This prevents stale servers from consuming jobs after migration.

Primary Analysis Server:
ANALYSIS_WORKER_ENABLED=true

Old / stale Analysis Server:
ANALYSIS_WORKER_ENABLED=false
service disabled/stopped

21. Security & Access Control

• Verify owner/project membership before export creation.
• Resolve source layer only within the authorized tenant/project.
• Never accept a raw arbitrary database table name directly from the client.
• Resolve table names from trusted layer metadata.
• Sanitize output filenames and internal layer names.
• Use parameterized SQL / GDAL-safe identifier quoting.
• Presigned object URLs should be short-lived.
• Do not expose storage secret keys to the browser.
• Audit operator_id for export and download events.

22. Performance Design

22.1 Raster

22.2 Vector

22.3 Temporary files

Generated export artifacts should be stored in an isolated temporary/export workspace with retention cleanup. Direct S3 TIFF downloads need no temporary file.

23. Suggested API / Job Contract

23.1 Raster request

{
  "analysis_id": "raster.export",
  "project_id": 428,
  "input_layer_id": 1234,
  "params": {
    "output_format": "GTiff",
    "target_epsg": 4326,
    "target_resolution": 0,
    "resampling": "bilinear"
  }
}

23.2 Vector request

{
  "analysis_id": "vector.export",
  "project_id": 428,
  "input_layer_id": 5678,
  "params": {
    "output_format": "GPKG",
    "target_epsg": 4326
  }
}

23.3 Completed export response

{
  "status": "completed",
  "output_kind": "export",
  "export_id": "...",
  "format": "GPKG",
  "filename": "roads.gpkg",
  "download_url": "/api/.../exports/.../download"
}

24. UI Contract

No dedicated HTML page is required if the analysis UI is metadata/form driven. The analysis definition can expose the fields, choices and defaults.

24.1 Raster Export form

Input Raster
Output Format
  - TIFF
  - ECW

Target CRS
Target Resolution
  - 0 / Auto
  - custom pixel size

Resampling
Export

24.2 Vector Export form

Input Vector Layer
Output Format
  - GeoPackage
  - ESRI Shapefile
  - GeoJSON
  - KML
  - AutoCAD DXF

Target CRS
Export

24.3 Recommended English labels

25. QA / Regression Checklist

25.1 Raster Export

• TIFF direct export returns the existing raster without rewriting it.
• Direct export uses correct virtual-hosted object-storage URL.
• Browser filename does not become .tif.tif.
• Different EPSG triggers reprojection.
• Non-zero target resolution triggers resampling.
• Classification raster defaults to nearest-neighbour when applicable.
• Transformed TIFF is valid and readable.
• ECW failure is isolated if driver unavailable.
• No layer, commit or revision is created.
• Export/download audit is created.

25.2 Vector Export

• GeoPackage opens and has correct CRS/geometry/attributes.
• Shapefile ZIP contains all required sidecar files.
• GeoJSON interoperability/CRS behavior is correct.
• KML is EPSG:4326.
• DXF geometry is transformed before export when target CRS is selected.
• Very large layer is exported without loading the entire table into application RAM.
• No layer, commit or revision is created.
• Export/download audit is created.

25.3 Worker Regression

• raster.export is found by the active worker.
• vector.export is found by the active worker.
• Only intended worker instances claim jobs.
• Existing ~100+ analysis methods remain registered and unchanged.
• Adding export does not replace/reorder unrelated registry entries unnecessarily.

26. Practical Examples

26.1 Fast raster download

Source:
orthomosaic_2026.tif
CRS: EPSG:32749

Request:
TIFF
EPSG:32749
Resolution: Auto / 0

Result:
→ direct S3 presigned download
→ no raster rewrite

26.2 Raster export to another CRS

Source:
classification.tif
EPSG:32749

Request:
TIFF
EPSG:4326
Resolution: 0
Resampling: Nearest

Result:
→ GDAL reprojection
→ COG
→ temporary export
→ browser download

26.3 ECW

Source:
large_ortho.tif

Request:
ECW
Target CRS: source CRS
Target Resolution: 0.25

Result:
→ optional resample
→ ECW write
→ download

If ECW driver is missing:
→ clear ECW-specific error
→ TIFF export remains unaffected

26.4 Large PostGIS vector to GeoPackage

public.layers.spatial_table
= parcel_428_abc123

Request:
GeoPackage
EPSG:4326

Result:
PostGIS → ogr2ogr → parcel.gpkg
→ export audit
→ download

26.5 Shapefile compatibility export

PostGIS
→ ogr2ogr ESRI Shapefile
→ generate .shp/.shx/.dbf/.prj/.cpg
→ ZIP
→ download