CRS Transformation

Prerequisites

• spatialpack CLI installed (pip install -e ".[full]")
• A spatial file (GeoParquet, Shapefile, GeoPackage, or GeoJSON) with a known CRS

Steps

1. Detect the current CRS

Before transforming data, inspect the coordinate reference system attached to the file.

spatialpack crs detect ./data/cadastre.shp

Expected output:

CRS Detection Results
  File:       ./data/cadastre.shp
  CRS:        EPSG:28350 (GDA94 / MGA zone 50)
  Confidence: HIGH
  Area of Use: Australia - 114E to 120E

The crs detect command reads the file’s embedded CRS metadata and reports the EPSG code, human-readable name, and area of use.

2. List supported coordinate reference systems

See all CRS definitions the normalizer supports. This is useful when you need the EPSG code for a target projection.

spatialpack crs list --australian-only

Expected output:

Supported Australian CRS
  EPSG:4283  GDA94 (geographic)
  EPSG:7844  GDA2020 (geographic)
  EPSG:28349 GDA94 / MGA zone 49
  EPSG:28350 GDA94 / MGA zone 50
  EPSG:28351 GDA94 / MGA zone 51
  EPSG:7849  GDA2020 / MGA zone 49
  EPSG:7850  GDA2020 / MGA zone 50
  EPSG:7851  GDA2020 / MGA zone 51
  ...

MGA (Map Grid of Australia) zones are projected CRS used for area and distance calculations. Each zone covers a 6-degree band of longitude.

3. Validate CRS and area of use

Check whether the data coordinates fall within the expected area for the declared CRS. This catches common issues like data projected in the wrong MGA zone.

spatialpack crs validate ./data/cadastre.shp

Expected output:

CRS Validation Results
  File:       ./data/cadastre.shp
  CRS:        EPSG:28350 (GDA94 / MGA zone 50)
  Status:     PASS
  Bounds check: coordinates within area of use

If the data falls outside the CRS area of use, the validator suggests a better-matching CRS.

4. Normalize a vector file to WGS84

Transform a file from its detected CRS to WGS84 (EPSG:4326), the standard storage CRS for Spatial Packs. The normalizer tracks full CRS provenance metadata.

spatialpack crs normalize ./data/cadastre.shp -o ./data/cadastre_wgs84.parquet

Expected output:

CRS Normalization
  Source CRS:  EPSG:28350 (GDA94 / MGA zone 50)
  Target CRS:  EPSG:4326 (WGS 84)
  Features:    12,345
  Output:      ./data/cadastre_wgs84.parquet

The output file includes CRS provenance metadata recording the source CRS, target CRS, and transformation method used. This metadata is preserved in the GeoParquet file for downstream audit.

5. Transform to a different projected CRS

Target a CRS other than WGS84 by specifying --target-crs. This is useful when your downstream analysis requires a projected CRS for accurate area and distance calculations.

spatialpack crs normalize ./data/cadastre.shp \
  -o ./data/cadastre_gda2020.parquet \
  --target-crs EPSG:7850

Expected output:

CRS Normalization
  Source CRS:  EPSG:28350 (GDA94 / MGA zone 50)
  Target CRS:  EPSG:7850 (GDA2020 / MGA zone 50)
  Features:    12,345
  Output:      ./data/cadastre_gda2020.parquet

This transforms from GDA94 to GDA2020, the modern Australian datum. The transformation uses the best available method, preferring the NTv2 grid (sub-centimeter accuracy) when available, falling back to a 7-parameter conformal transformation (~1 m accuracy).

6. Override the source CRS

If a file has missing or incorrect CRS metadata, specify the source CRS explicitly.

spatialpack crs normalize ./data/unknown_crs.shp \
  -o ./data/output.parquet \
  --source-crs EPSG:28350

This tells the normalizer to treat the input coordinates as GDA94 / MGA zone 50 regardless of what the file metadata says.

7. Normalize a raster file

Raster files (GeoTIFF) use a separate command optimized for pixel-based reprojection.

spatialpack crs normalize-raster ./data/dem_mga50.tif \
  -o ./data/dem_wgs84.tif \
  --resampling bilinear

Expected output:

Raster CRS Normalization
  Source CRS:   EPSG:28350 (GDA94 / MGA zone 50)
  Target CRS:   EPSG:4326 (WGS 84)
  Resampling:   bilinear
  Output:       ./data/dem_wgs84.tif

The --resampling option controls how pixel values are interpolated during reprojection. Use bilinear for continuous data like elevation, nearest for categorical data like land use classification.

8. Batch normalize a directory

Transform all spatial files in a directory at once.

spatialpack crs normalize ./data/ --batch --pattern "*.shp,*.geojson"

Expected output:

Batch Normalization
  Directory:   ./data/
  Patterns:    *.shp, *.geojson
  Files found: 5
  Normalized:  5/5

Each file is normalized to WGS84 by default. The output files are written alongside the originals with a _normalized suffix.

Tip

Why WKT2 over EPSG codes? The spatialpack CLI uses WKT2 (Well-Known Text version 2) internally for CRS representation. WKT2 is more precise than EPSG codes alone because it encodes the full datum definition, coordinate axis order, and transformation parameters. EPSG codes are convenient shorthand, but WKT2 eliminates ambiguity — especially for datum transformations between GDA94 and GDA2020 where the choice of transformation method affects accuracy.

9. Understand the CRS cascade

When the CLI normalizes a file, it resolves the source CRS using a 3-step cascade:

1. Explicit — If you pass --source-crs, that value is used directly.
2. Metadata — The CLI reads CRS metadata from the file (.prj for Shapefiles, embedded metadata for GeoParquet and GeoPackage).
3. Australian datum fallback — If no CRS is detected and the coordinates fall within Australian bounds, the CLI applies Australian datum heuristics (GDA94 or GDA2020) and auto-selects the appropriate MGA zone.

This cascade means most Australian datasets “work” without manual CRS specification, while international datasets require explicit metadata or a --source-crs override.

Next steps

• CLI crs reference — Full list of options for spatialpack crs commands
• Pipeline Architecture — How CRS normalization fits into the automated build pipeline
• Data Formats — Why GeoParquet is the standard output format for normalized data