Géo

En bref

NextPDF Pro mappe les coordonnées de page PDF vers des coordonnées géographiques et génère un dictionnaire de mesure PDF avec le sous-type GEO, afin qu’une visionneuse puisse rapporter la position réelle à partir d’un point de la page.

Disponibilité et licence

Cette capacité est livrée dans NextPDF Pro (nextpdf/pro) et s’active avec une enveloppe de licence de niveau Pro. Un déploiement sans ce droit ne charge pas les classes de la capacité. Compare les éditions et obtiens une licence.

Geo n’a pas d’indicateur de licence distinct par fonctionnalité ; l’enveloppe de niveau Pro l’active directement.

Installation

composer require nextpdf/pro:^3

Aperçu conceptuel

Un PDF géospatial porte un dictionnaire de mesure, décrit dans ISO 32000-2 §12.8.2, qui relie les points de l’espace-périphérique à un système de référence de coordonnées géographiques. NextPDF Pro construit ces données à partir d’objets-valeurs immuables :

• GeoCoordinate — un triplet latitude/longitude/altitude. La construction valide la latitude dans [-90, 90] et la longitude dans [-180, 180], et offre un formatage en degrés-minutes-secondes et en chaîne décimale.
• GeoControlPoint — un appariement d’un point en espace PDF avec une GeoCoordinate.
• ProjectionType — une énumération des projections courantes (géographique, UTM, Mercator transverse, conique conforme de Lambert), chacune mappée à un code EPSG.
• GeoRegistration — les points de contrôle plus la projection et le datum géodésique (par défaut WGS84). isValid() requiert au moins deux points de contrôle pour une transformation affine minimale ; toPdfMeasureDictionary() émet le dictionnaire /Measure avec /Subtype /GEO et les tableaux de points de contrôle.

Pourquoi ça fonctionne ainsi

NextPDF construit le dictionnaire de mesure à partir d’objets-valeurs validés et immuables, et non d’un dictionnaire brut fourni par l’appelant. GeoCoordinate rejette une latitude ou une longitude hors plage à la construction. GeoRegistration::isValid() refuse moins de deux points de contrôle, de sorte qu’un calage mal formé échoue rapidement au lieu d’émettre un dictionnaire /GEO dégradé. Les projections se résolvent en codes EPSG standard via ProjectionType, ce qui garde le système de référence de coordonnées explicite plutôt que deviné. Le datum vaut WGS84 par défaut mais reste un champ nommé, de sorte qu’un système de référence non par défaut est un choix délibéré. Cette posture fail-closed est importante, car une géoréférence erronée est pire que son absence ; une visionneuse rapporterait avec assurance une fausse position réelle. Contexte de conception : Une API qui refuse de deviner.

Surface d’API

Classe	Responsabilité
GeoCoordinate	Latitude/longitude/altitude validées avec formatage.
GeoControlPoint	Appariement point PDF ↔ point géographique.
ProjectionType	Énumération de projection avec codes EPSG.
GeoRegistration	Construit le dictionnaire /Measure /GEO.

Exemple de code — Démarrage rapide

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();

Exemple de code — 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,
]);

Cas limites et pièges

• La construction de GeoCoordinate rejette une latitude ou une longitude hors plage.
• Moins de deux points de contrôle produit un calage invalide.
• Le datum par défaut est WGS84 ; définis-le explicitement pour d’autres systèmes de référence.

Performance

La génération du dictionnaire est linéaire par rapport au nombre de points de contrôle.

Notes de sécurité

L’entrée de Geo est constituée de données de coordonnées numériques. Valide les points de contrôle issus d’une entrée non fiable avant le calage.

Conformité

Comportement	Référence	Statut
Dictionnaire de mesure géospatiale (sous-type GEO)	ISO 32000-2 §12.8.2	Aligné (paraphrasé)

Contrat de comportement

• GeoCoordinate valide la latitude dans [-90, 90] et la longitude dans [-180, 180] à la construction et offre un formatage DMS et en chaîne décimale.
• GeoControlPoint apparie un point en espace PDF avec une GeoCoordinate.
• GeoRegistration porte les points de contrôle plus un ProjectionType (mappé à un code EPSG) et un datum géodésique valant par défaut WGS84. isValid() requiert au moins deux points de contrôle ; toPdfMeasureDictionary() émet un dictionnaire /Measure avec /Subtype /GEO et les tableaux de points de contrôle.
• Des coordonnées hors plage ou moins de deux points de contrôle produisent un calage invalide plutôt qu’une sortie silencieusement dégradée.

Note de frontière Enterprise

Enterprise ne change pas le comportement de Geo. Enterprise ajoute des fonctionnalités de niveau supérieur, documentées séparément ; elles ne sont pas requises pour générer un dictionnaire de mesure GeoPDF.

Repli / alternative Core

Il n’existe aucun équivalent Core pour la génération de dictionnaire de mesure GeoPDF. C’est un ajout de Pro.

Limite de publication

Cette page ne documente que le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins d’espace de noms internes, les classes d’assistance, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de ticket sont hors périmètre.

Voir aussi

• Geo — Référence approfondie — référence complète des classes et méthodes.
• Document — assemblage de pages et de documents.
• Annotations de Core.