Geo — Référence détaillée

En un coup d’œil

Cette page est la référence au niveau du contrat pour le module Geo de NextPDF Pro. La surface se compose de quatre objets-valeurs immuables — GeoCoordinate, GeoControlPoint, ProjectionType et GeoRegistration — auxquels s’ajoute GeoPdfLayer, qui associe des enregistrements à des indices de page et émet la sortie viewport. Le module produit du texte de dictionnaire PDF : un dictionnaire /Measure avec /Subtype /GEO, un dictionnaire /Viewport et la valeur de tableau /VP au niveau page. La génération est un assemblage de chaînes déterministe : aucun appel réseau, aucun accès au système de fichiers, aucun aléa. Cette page énonce l’API publique, le contrat de comportement observable et les modes de défaillance.

Disponibilité et licence

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

Aucun indicateur de licence propre à la fonctionnalité ne conditionne ce module. Les classes Geo sont disponibles dès que nextpdf/pro est installé.

Surface de l’API publique

Symbole	Paramètres	Comportement par défaut	Renvoie	Lève ou échoue avec	Notes
GeoCoordinate	constructeur : float $latitude, float $longitude, float $altitude = 0.0	Valide la latitude dans [-90, 90] et la longitude dans [-180, 180]	—	InvalidArgumentException lorsque l’une des valeurs est hors plage	final readonly ; l’altitude est en mètres au-dessus du niveau de la mer et n’est pas contrôlée en plage
GeoCoordinate::toDms()	aucun	Formate en degrés-minutes-secondes avec les suffixes N/S et E/W	string	—	Les secondes quasi nulles s’affichent 00 ; sinon deux décimales avec les zéros de fin supprimés
GeoCoordinate::toDecimal()	aucun	Formate la latitude et la longitude à six décimales, séparées par une virgule	string	—	L’altitude n’est pas incluse
GeoCoordinate::fromDms()	string $dms	Analyse une chaîne DMS ; les secondes sont facultatives ; les glyphes typographiques de degré et de guillemet sont normalisés	self	InvalidArgumentException lorsque la chaîne ne s’analyse pas, ou lorsque les valeurs analysées échouent aux contrôles de plage du constructeur	Fabrique statique ; les lettres d’hémisphère sont insensibles à la casse ; l’altitude vaut 0.0 par défaut
GeoControlPoint	constructeur : float $pdfX, float $pdfY, GeoCoordinate $geo	Associe un point de l’espace utilisateur PDF (en points) à une coordonnée géographique	—	—	final readonly ; les coordonnées PDF ne sont pas validées
ProjectionType	énumération adossée à des chaînes, 4 cas	Cas : Geographic, UTM, TransverseMercator, LambertConformal	valeurs sous-jacentes GEO, UTM, TM, LCC	—	Voir la table de correspondance des projections ci-dessous
ProjectionType::epsgCode()	aucun	Fait correspondre le cas à un unique code EPSG fixe	int	—	4326, 32601, 2154 ou 3347
ProjectionType::label()	aucun	Nom de projection lisible par un humain	string	—	Par exemple WGS 84 Geographic
GeoRegistration	constructeur : array $controlPoints, ProjectionType $projection, string $datum = 'WGS84'	Contient les points de contrôle, la projection et le datum géodésique	—	—	final readonly ; le nombre de points de contrôle n’est pas validé à la construction
GeoRegistration::isValid()	aucun	Exige au moins deux points de contrôle	bool	—	Deux points constituent le minimum pour une correspondance affine
GeoRegistration::toPdfMeasureDictionary()	aucun	Émet un dictionnaire /Measure avec /Subtype /GEO, /GCS, /GPTS, /LPTS et /Bounds	string	—	Ne vérifie pas isValid() ; protège l’appel ou passe par GeoPdfLayer
GeoPdfLayer::addRegistration()	int $pageIndex, GeoRegistration $registration	Ajoute un enregistrement pour un indice de page à base zéro	self	InvalidArgumentException lorsque $pageIndex est négatif	Fluide ; le premier enregistrement ajouté pour une page l’emporte au moment de la génération
GeoPdfLayer::getRegistrations()	aucun	Renvoie tous les enregistrements dans l’ordre d’insertion	list<array{pageIndex: int, registration: GeoRegistration}>	—	Inclut les doublons et les enregistrements invalides tels qu’ajoutés
GeoPdfLayer::generateViewportDictionary()	int $pageIndex	Émet un dictionnaire /Viewport avec /BBox, /Name et un /Measure en ligne	string	—	Chaîne vide lorsque la page n’a aucun enregistrement ou que l’enregistrement est invalide
GeoPdfLayer::generateViewportArray()	int $pageIndex	Enveloppe le dictionnaire viewport entre crochets pour former le littéral de tableau /VP	string	—	Chaîne vide en cas d’absence ; les appelants omettent alors /VP pour cette page
GeoPdfLayer::writeToPdfWriter()	BinaryBuffer $buffer, int $pageIndex	Écrit /VP suivi du littéral de tableau et d’un saut de ligne dans le buffer	bool	—	true lorsqu’une entrée a été écrite ; sans effet et false sinon

Signatures des points d’entrée

public function __construct(
    public float $latitude,
    public float $longitude,
    public float $altitude = 0.0,
)

public function toDms(): string

public function toDecimal(): string

public static function fromDms(string $dms): self

public function __construct(
    public float $pdfX,
    public float $pdfY,
    public GeoCoordinate $geo,
)

public function __construct(
    public array $controlPoints,
    public ProjectionType $projection,
    public string $datum = 'WGS84',
)

public function isValid(): bool

public function toPdfMeasureDictionary(): string

public function addRegistration(int $pageIndex, GeoRegistration $registration): self

public function getRegistrations(): array

public function generateViewportDictionary(int $pageIndex): string

public function generateViewportArray(int $pageIndex): string

public function writeToPdfWriter(BinaryBuffer $buffer, int $pageIndex): bool

Contrat de comportement

Validation et formatage des coordonnées

GeoCoordinate valide à la construction et ne mute jamais. Une latitude hors de [-90, 90] ou une longitude hors de [-180, 180] lève InvalidArgumentException en nommant la valeur fautive. toDms() restitue les deux axes sous forme de degrés, de minutes complétées par des zéros, de secondes et d’un suffixe d’hémisphère. toDecimal() restitue latitude, longitude à six décimales. fromDms() accepte une entrée DMS aux secondes facultatives, normalise les glyphes de prime, double-prime, signe degré et guillemet typographique, convertit en degrés décimaux signés et construit une nouvelle instance. Les latitudes sud et les longitudes ouest deviennent des valeurs négatives.

Correspondance des projections

Chaque cas de ProjectionType porte un code EPSG fixe et un libellé. La correspondance est une table fermée, non un registre de systèmes de référence de coordonnées.

Cas	Valeur sous-jacente	epsgCode()	label()
Geographic	GEO	4326	WGS 84 Geographic
UTM	UTM	32601	Universal Transverse Mercator
TransverseMercator	TM	2154	Transverse Mercator
LambertConformal	LCC	3347	Lambert Conformal Conic

Le cas UTM émet le code de la zone 1. Les projets qui ont besoin d’une autre zone UTM, ou de tout code EPSG hors de cette table, doivent porter la description CRS faisant autorité dans la chaîne datum sous forme de Well Known Text.

Émission du dictionnaire de mesure

GeoRegistration::toPdfMeasureDictionary() émet un dictionnaire multiligne : /Type /Measure, /Subtype /GEO, un dictionnaire de système de coordonnées /GCS, /GPTS, /LPTS et /Bounds, conformément à ISO 32000-2:2020 §12.10 (Table 269). Comportement concret :

• /GCS est émis sous la forme << /Type /PROJCS /EPSG <code> /WKT (<datum>) >>. Le code EPSG provient du cas de projection. La valeur /WKT est la chaîne datum exactement telle que fournie ; la valeur par défaut est WGS84.
• /GPTS liste les paires latitude-longitude à six décimales, dans l’ordre des points de contrôle.
• /LPTS liste les paires pdfX/pdfY à six décimales, exactement telles que fournies. La Table 269 d’ISO 32000-2:2020 définit les points LPTS dans un carré unité 2D ; fournir des valeurs normalisées sur le carré unité relève de la responsabilité de l’appelant.
• /Bounds est fixé à [0 0 0 1 1 1 1 0], le carré unité complet.
• La chaîne datum est échappée avant son interpolation dans la chaîne littérale : la barre oblique inverse, les parenthèses et les caractères de contrôle courants deviennent leurs échappements par barre oblique inverse conformément à ISO 32000-2:2020 §7.3.4.2. Un datum influencé par l’appelant ne peut ni terminer la chaîne littérale ni injecter de jetons PDF bruts.

Émission du viewport et de la page

GeoPdfLayer conserve les enregistrements dans l’ordre d’insertion, indexés par indice de page à base zéro. generateViewportDictionary() résout le premier enregistrement pour la page demandée et renvoie une chaîne vide lorsqu’aucun n’existe ou que isValid() est faux. Un dictionnaire produit porte /Type /Viewport, un /BBox calculé à partir des coordonnées PDF minimales et maximales des points de contrôle, un /Name de la forme GeoViewport_Page<n> et le dictionnaire /Measure en ligne. L’entrée /Measure du viewport suit ISO 32000-2:2020 §12.9. generateViewportArray() enveloppe le dictionnaire entre crochets, produisant la valeur /VP de la page : un tableau de dictionnaires de viewport conformément à ISO 32000-2:2020 §7.7.3.3 (Table 31). writeToPdfWriter() écrit /VP suivi du littéral de tableau dans un BinaryBuffer de Core et signale si quelque chose a été écrit, afin que la sérialisation de page puisse omettre proprement la clé.

Cas limites et modes de défaillance

• Une latitude ou une longitude hors plage lève InvalidArgumentException à la construction ; aucune coordonnée partiellement valide n’existe.
• fromDms() lève une exception sur une entrée inanalysable. Les valeurs analysées passent par le constructeur, de sorte qu’une chaîne syntaxiquement valide avec des valeurs hors plage lève également une exception.
• La notation DMS ne porte aucune altitude ; fromDms() produit toujours l’altitude 0.0.
• Un GeoRegistration comptant moins de deux points de contrôle rapporte isValid() faux, et pourtant toPdfMeasureDictionary() émet quand même un dictionnaire avec des tableaux de points tronqués. Protège les appels directs avec isValid(), ou fais passer l’émission par GeoPdfLayer, qui supprime les enregistrements invalides.
• Les enregistrements en double pour un même indice de page sont tous conservés par getRegistrations() ; la génération de viewport utilise le premier ajouté.
• Un indice de page négatif lève InvalidArgumentException ; les indices de page sont à base zéro.
• Des points de contrôle qui partagent une valeur X ou Y produisent un /BBox dégénéré de largeur ou de hauteur nulle. Fournis des points qui couvrent les deux axes.
• Toute la sortie est du texte généré. Rien n’est écrit sur le disque ni sur le réseau, et une entrée identique produit une sortie identique.
• Aucune opération cryptographique n’a lieu dans ce module, il n’existe donc aucun comportement spécifique au mode FIPS.

Conformité

Affirmation	Norme	Clause
Le dictionnaire de mesure est émis avec le sous-type GEO, avec des paires latitude-longitude GPTS et des valeurs LPTS appariées.	ISO 32000-2:2020	§12.10
Le dictionnaire de viewport porte les entrées BBox, Name et Measure.	ISO 32000-2:2020	§12.9
La valeur VP de la page est émise sous forme de tableau de dictionnaires de viewport.	ISO 32000-2:2020	§7.7.3.3
L’interpolation du datum échappe les métacaractères de chaîne littérale.	ISO 32000-2:2020	§7.3.4.2

Toutes les clauses sont paraphrasées ; NextPDF ne reproduit aucun texte normatif. Il s’agit d’énoncés de capacité, non de certifications. NextPDF ne détient aucune certification et n’en accorde aucune. Les codes EPSG sont des valeurs représentatives fixes par cas de projection, et l’entrée /WKT porte la chaîne datum fournie plutôt qu’une description Well Known Text générée ; les deux énoncés sont ancrés dans le produit. Valide la sortie GeoPDF émise dans les processeurs PDF interactifs cibles avant de te fier à la mesure côté visionneuse.

Notes de développement

• Disponible depuis nextpdf/pro 1.9.0 ; à jour dans nextpdf/pro 3.1.0.
• Vérifie isValid() avant d’appeler toPdfMeasureDictionary() directement ; GeoPdfLayer effectue cette vérification pour toi.
• Lorsque des consommateurs en aval analysent /WKT, passe une description Well Known Text complète comme datum ; la valeur par défaut WGS84 n’est qu’un libellé de datum.
• Normalise les entrées LPTS sur le carré unité avant de construire les points de contrôle lorsque les bornes du viewport diffèrent de tes valeurs en espace PDF.
• Le coût d’émission est linéaire en fonction du nombre de points de contrôle ; la recherche dans GeoPdfLayer est linéaire en fonction du nombre d’enregistrements.
• writeToPdfWriter() s’intègre à la sérialisation de page via NextPDF\Support\BinaryBuffer de Core.

Limite de publication

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

Voir aussi

• Geo (fonctionnalité) — installation, présentation conceptuelle et exemples de démarrage rapide.
• Document — Référence détaillée — la surface de composition de document et de page.