Geo

At a glance

NextPDF Pro maps PDF page coordinates to geographic coordinates and generates a PDF measure dictionary with the GEO subtype, so a viewer can report real-world position from a point on the page.

Availability & licensing

This capability ships in NextPDF Pro (nextpdf/pro) and activates with a Pro-tier license envelope. A deployment without that entitlement does not load the capability’s classes. Compare editions and get a license.

Geo has no separate per-feature license flag; the Pro-tier envelope enables it directly.

Install

composer require nextpdf/pro:^3

Conceptual overview

A geospatial PDF carries a measure dictionary, described in ISO 32000-2 §12.8.2, that ties device-space points to a geographic coordinate reference system. NextPDF Pro builds that data from immutable value objects:

• GeoCoordinate — a latitude/longitude/altitude triple. Construction validates latitude within [-90, 90] and longitude within [-180, 180], and offers degrees-minutes-seconds and decimal string formatting.
• GeoControlPoint — a pairing of a PDF-space point with a GeoCoordinate.
• ProjectionType — an enum of common projections (geographic, UTM, transverse Mercator, Lambert conformal conic), each mapped to an EPSG code.
• GeoRegistration — the control points plus projection and geodetic datum (default WGS84). isValid() requires at least two control points for a minimal affine transform; toPdfMeasureDictionary() emits the /Measure dictionary with /Subtype /GEO and the control-point arrays.

Why it works this way

NextPDF builds the measure dictionary from validated, immutable value objects, not from a raw dictionary supplied by the caller. GeoCoordinate rejects an out-of-range latitude or longitude at construction. GeoRegistration::isValid() refuses fewer than two control points, so a malformed registration fails fast instead of emitting a degraded /GEO dictionary. Projections resolve to standard EPSG codes through ProjectionType, which keeps the coordinate reference system explicit rather than guessed. The datum defaults to WGS84 but stays a named field, so a non-default reference system is a deliberate choice. This fail-closed posture matters because a wrong georeference is worse than none; a viewer would confidently report a false real-world position. Design background: An API that refuses to guess.

API surface

Class	Responsibility
GeoCoordinate	Validated lat/lon/altitude with formatting.
GeoControlPoint	PDF point ↔ geographic point pairing.
ProjectionType	Projection enum with EPSG codes.
GeoRegistration	Build the /Measure /GEO dictionary.

Code sample — Quick start

use NextPDF\Pro\Geo\{GeoRegistration, GeoControlPoint, GeoCoordinate, ProjectionType};

$reg = new GeoRegistration(
    controlPoints: [
        new GeoControlPoint(0.0, 0.0, new GeoCoordinate(40.0, -74.0, 0.0)),
        new GeoControlPoint(600.0, 800.0, new GeoCoordinate(41.0, -73.0, 0.0)),
    ],
    projection: ProjectionType::Geographic,
);
$dict = $reg->toPdfMeasureDictionary();

Code sample — Production

if (! $reg->isValid()) {
    throw new RuntimeException('Geo registration needs at least two control points.');
}
$logger->info('geo.registered', [
    'projection' => $reg->projection->value,
    'datum'      => $reg->datum,
]);

Edge cases & gotchas

• GeoCoordinate construction rejects an out-of-range latitude or longitude.
• Fewer than two control points produces an invalid registration.
• The default datum is WGS84; set it explicitly for other reference systems.

Performance

Dictionary generation is linear in the number of control points.

Security notes

Geo input is numeric coordinate data. Validate control points sourced from untrusted input before registration.

Conformance

Behavior	Reference	Status
Geospatial measure dictionary (GEO subtype)	ISO 32000-2 §12.8.2	Aligned (paraphrased)

Behavior contract

• GeoCoordinate validates latitude within [-90, 90] and longitude within [-180, 180] at construction and offers DMS and decimal string formatting.
• GeoControlPoint pairs a PDF-space point with a GeoCoordinate.
• GeoRegistration carries control points plus a ProjectionType (mapped to an EPSG code) and a geodetic datum defaulting to WGS84. isValid() requires at least two control points; toPdfMeasureDictionary() emits a /Measure dictionary with /Subtype /GEO and the control-point arrays.
• Out-of-range coordinates or fewer than two control points produce an invalid registration rather than silently degraded output.

Enterprise boundary note

Enterprise does not change Geo behavior. Enterprise adds higher-tier features documented separately; they are not required to generate a GeoPDF measure dictionary.

Core fallback / alternative

There is no Core equivalent for GeoPDF measure-dictionary generation. This is a Pro addition.

Publication boundary

This page documents externally observable behavior and the supported public API surface only. Internal namespace paths, helper classes, mechanism tables, runbook filenames, and ticket prefixes are out of scope.

See also

• Geo — Deep Reference — full class and method reference.
• Document — page and document assembly.
• Core navigation and annotations.