proj-knowledge-patch

# PROJ Knowledge Patch Use this skill when building PROJ, consuming its C or C++ APIs, invoking `projinfo`, parsing CRS formats, selecting coordinate operations, or diagnosing changed transformation results. ## Apply the patch 1. Determine the PROJ version from the package metadata, `proj`/`projinfo` executable, CMake package, or `proj.h`. 2. Read the quick-reference sections below before changing a build or accepting a changed coordinate result. 3. Open only the topic reference needed for the task. 4. Apply notes introduced no later than the installed version. 5. Prefer the installed database, generated build metadata, application tests, and observed transformations when they disagree with compatibility guidance. 6. For numerical changes, compare complete pipelines, grids, epochs, axis order, and database records before treating a result difference as a regression. ## Reference index | Reference | Topics | | --- | --- | | [build-and-runtime.md](references/build-and-runtime.md) | CMake, C++17, embedded resources, TLS, network grids, WebAssembly, packaging | | [crs-formats-and-database.md](references/crs-formats-and-database.md) | EPSG/ESRI data, WKT, PROJJSON, identification, aliases, operation methods | | [operation-selection.md](references/operation-selection.md) | Compound and vertical CRS operations, realization transforms, epochs, extent filtering | | [projections-and-geodesy.md](references/projections-and-geodesy.md) | Projection additions and numerical changes, geodesic APIs | | [bounds-cli-and-context.md](references/bounds-cli-and-context.md) | Bounds transforms, `projinfo`, cloning, lookup, library integration | ## Highest-impact compatibility checks ### Account for the EPSG database rollback Treat the database bundled with 9.8.1 as EPSG 12.029, not 12.049. Records added with 9.8.0, chiefly `ETRS89-XXX` national datum and CRS definitions, are absent after the rollback. Do not assume a failure to find those records is an API failure. When deployment behavior differs: 1. Record both the PROJ library version and database metadata. 2. Check whether the application relies on an `ETRS89-XXX` national realization added with the newer database. 3. Avoid copying a 9.8.0 database into a 9.8.1 installation without validating transformation behavior and packaging expectations. 4. Re-run operation discovery for Austria, Belgium, Catalonia, the Netherlands, Romania, and Serbia; the rollback specifically avoids ETRS89 regressions affecting those areas. See [crs-formats-and-database.md](references/crs-formats-and-database.md). ### Expect corrected transformation choices Do not pin a pipeline merely because an older release selected it. Operation selection now handles more vertical, compound, realization, and epoch cases. Changed results may reflect a corrected pipeline rather than numerical drift. Check these inputs: - Source and target CRS dimensionality. - Vertical datum identity and units. - Coordinate epoch for time-dependent transformations. - Required grids and their actual download location. - `CRS_EXTENT_USE`, visualization normalization, and desired longitude overrange behavior. - Whether a cloned `PJ` retains all source flags. See [operation-selection.md](references/operation-selection.md). ### Revalidate corrected projection numerics Update golden values when they encoded earlier defects. In particular, verify: - Wagner VI results after its parameter correction. - Inverse authalic-latitude results for equal-area projections. - Antimeridian and global bounds calculations. - Spherical Transverse Mercator values at the latitude of origin. - Projected CRS identification when input and candidate ellipsoids differ. Use tolerances appropriate to the operation, but do not widen tolerances before confirming that the selected pipeline and database are equivalent. See [projections-and-geodesy.md](references/projections-and-geodesy.md) and [bounds-cli-and-context.md](references/bounds-cli-and-context.md). ## Build and deployment quick reference ### Require a C++17-capable toolchain Compile PROJ and downstream C++ integration with C++17 support. If a build environment previously relied on an older language mode, update the compiler, standard-library configuration, and consumer target features together. ### Choose an embedded-resource mode deliberately Use the CMake switches as a coordinated set: ```sh cmake -S . -B build \ -DEMBED_RESOURCE_FILES=ON \ -DUSE_ONLY_EMBEDDED_RESOURCE_FILES=ON \ -DEMBED_RESOURCE_DIRECTORY=/path/to/resources ``` `EMBED_RESOURCE_FILES` embeds `proj.db` and `proj.ini`. `USE_ONLY_EMBEDDED_RESOURCE_FILES` restricts use to embedded resources. `EMBED_RESOURCE_DIRECTORY` adds `.tif` and `.json` resources to `libproj`. Test the exact compiler and platform combination. Older compilers must not be treated as supporting C23 `#embed`, and Windows supports enabling both resource switches together. ### Configure native trust stores explicitly Set `native_ca` in `proj.ini` or its `PROJ_NATIVE_CA` environment equivalent when curl should use the operating-system CA store. Include SSL connection timeouts in network-failure tests because PROJ retries that failure mode. ### Treat WebAssembly fetching as platform-specific Expect Emscripten builds to retrieve remote resources through Emscripten Fetch. Exercise browser policy, URL reachability, caching, and error behavior in the actual WebAssembly deployment rather than assuming native curl behavior. See [build-and-runtime.md](references/build-and-runtime.md). ## CRS parsing and serialization quick reference ### Accept the Projected CRS `base_crs.type` When validating PROJJSON for a Projected CRS, allow an explicit `type` member in `base_crs`. Its value is `GeographicCRS` or `GeodeticCRS`. Update strict schemas and structural equality fixtures accordingly. ### Handle `DEFININGTRANSFORMATION` conservatively The WKT2 parser accepts `DEFININGTRANSFORMATION`, but does not apply its contents. Parsing success therefore does not prove that the defining transformation affected the resulting object or coordinate operation. ### Permit empty datum ensembles Allow WKT and PROJJSON datum ensembles with no members. Do not reject them in a wrapper solely because earlier PROJ versions did. ### Expect legacy-name recognition to improve Name lookup and identification accept more historical EPSG and ESRI spellings, direction abbreviations, missing zones or heights, and `_IntlFeet` names. Preserve authority identifiers when available; use fuzzy names as an import compatibility path, not as a canonical serialization format. See [crs-formats-and-database.md](references/crs-formats-and-database.md). ## Bounds and API quick reference ### Use the bounds API that matches dimensionality Use `proj_trans_bounds()` for ordinary bounds, including a CompoundCRS target. Use `proj_trans_bounds_3D()` when the bounds themselves are three-dimensional. Retest extrema rather than transforming only corners: bounds processing samples the source grid to capture transformed extrema. For antimeridian-crossing geographic input, use a release containing the regression fix and keep a focused test. A `PJ*` created directly from a PROJ pipeline is also valid in cases that previously errored. ### Use new library entry points without reproducing CLI code Use `proj_geod_direct()` for a direct geodesic calculation with a `PJ` transformation object. For embedded `projinfo` behavior, include `projapps_lib.h` and use the exposed library functionality instead of scraping command output. ### Preserve context and clone semantics Expect `proj_clone()` to carry configuration flags, including `errorIfBestTransformationNotAvailable` and `FORCE_OVER=YES`. After `proj_download_file()` succeeds, expect caches associated with that file to be invalidated in the current context. See [bounds-cli-and-context.md](references/bounds-cli-and-context.md). ## Validation checklist - Confirm the actual library and database pair. - Rebuild with a C++17-capable toolchain. - Verify resource mode, grid availability, CA configuration, and fetch backend. - Parse and serialize representative WKT, PROJJSON, and legacy ESRI inputs. - Compare operation pipelines before comparing final coordinates. - Supply coordinate epochs for time-dependent cases. - Exercise compound and vertical CRS transformations in both directions. - Test antimeridian, global, 3D, and pipeline-created bounds objects. - Refresh numerical fixtures only after identifying the relevant correction. - Consult every linked topic that affects the changed behavior.