---

name: coordinate-transformations description: "Transform coordinates between pyproj CRS and projections with explicit axis-order, operation-selection, array, time, bounds, pipeline, and grid-availability checks." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

Coordinate transformations

Use this route when the job executes a coordinate operation: CRS-to-CRS conversion, a PROJ pipeline, a projection-only conversion, transformed bounds, or selection/diagnosis of alternative operations. Begin with references/workflows.md, then consult the focused references before choosing an operation.

Route and boundaries

• Use Transformer.from_crs for a CRS-to-CRS operation, including datum or coordinate-frame changes. Inspect the selected operation before trusting results.
• Use Transformer.from_pipeline when the operation is an explicit PROJ pipeline or an identified coordinate-operation object. Use TransformerGroup when alternatives, area-of-interest ranking, accuracy constraints, or missing grids must be compared.
• Use Proj only for a projection operation within the projection's own datum or for a deliberately specified PROJ projection. It is not a generic datum transformation tool.
• CRS construction, axis metadata, authority lookup, and database queries go to ../crs-and-database/SKILL.md.
• Network policy, PROJ data directories, grid discovery, and explicit grid synchronization go to ../cli-data-and-network/SKILL.md.
• Distance, area, azimuth, and ellipsoidal calculations go to ../geodesic-calculations/SKILL.md.

Minimum operating sequence

1. Write down source and target CRS, coordinate order, units, dimensionality (2D/3D/4D), geographic area, and whether the input is degrees or radians.
2. Validate the CRS definitions and their axis metadata through the CRS route. If application data is conventionally (longitude, latitude), create the transformer with always_xy=True and document that contract.
3. Create one reusable Transformer; do not use the deprecated module-level transform or itransform for new code. Apply Transformer.transform or itransform to scalar, array, or point-stream inputs.
4. For a datum-sensitive or regional conversion, select with an AreaOfInterest and appropriate authority, accuracy, and allow_ballpark constraints. Use only_best=True only when an unavailable best operation must be a hard error.
5. When operation availability is uncertain, inspect a TransformerGroup: compare transformers, unavailable_operations, best_available, operation descriptions, accuracies, and grid metadata. Do not infer that a missing grid is downloadable or that network access is permitted.
6. Validate the output shape, units, plausible range/area of use, and a reverse transformation when the operation has an inverse. Use errcheck=True at validation boundaries so invalid points fail explicitly; retain the default inf behavior only when the caller has a defined policy for invalid points.

Core contracts

• Inputs: CRS-compatible user inputs or an explicit pipeline; coordinate scalars, equal-shaped arrays, point iterables, optional z and t; optional area and operation-selection constraints.
• Outputs: transformed x, y and optional z, t with the input container family preserved where supported; an iterator for itransform; a four-value tuple for transform_bounds; operation metadata and group availability state for diagnostics.
• Expected signals: a transformer has a useful description, definition, accuracy, area_of_use, and (where supported) operations; a group makes best and unavailable alternatives visible. A successful numeric result is not by itself proof that the desired operation or axis convention was used.
• Recovery: first correct CRS/axis/unit assumptions, then inspect operation metadata and area of use, then classify missing-grid and data/network issues. Escalate data-directory and network changes to the CLI/data route rather than silently enabling remote access.

Focused references

• references/api-reference.md: signatures, parameters, return shapes, metadata, and API selection.
• references/workflows.md: repeatable workflows for CRS conversion, pipelines, arrays/time, bounds, and operation choice.
• references/axis-order-and-grids.md: axis traps, area and accuracy filters, TransformerGroup, and grid policy.
• references/troubleshooting.md: symptoms, checks, and recovery for invalid results, arrays, pipelines, axes, and grids.

Publication checks

Before handing this route to a caller, confirm that every transformation has an explicit coordinate order and unit contract, that any grid-dependent result records availability and fallback behavior, and that validation covers output shape plus at least one plausibility or round-trip check. Keep download and network side effects outside this route unless the caller has separately approved the CLI/data workflow.