Geo

한눈에 보기

NextPDF Pro는 PDF 페이지 좌표를 지리 좌표로 매핑하고 GEO 하위 유형의 PDF measure 딕셔너리를 생성하므로, 뷰어가 페이지의 한 점에서 실세계 위치를 보고할 수 있습니다.

가용성 및 라이선싱

이 기능은 NextPDF Pro(nextpdf/pro)로 제공되며 Pro 등급 라이선스 봉투로 활성화됩니다. 해당 자격이 없는 배포는 이 기능의 클래스를 로드하지 않습니다. 에디션을 비교하고 라이선스를 받으십시오.

Geo에는 기능별 별도의 라이선스 플래그가 없습니다. Pro 등급 봉투가 이를 직접 활성화합니다.

설치

composer require nextpdf/pro:^3

개념 개요

지리공간 PDF는 ISO 32000-2 §12.8.2에 설명된 measure 딕셔너리를 담으며, 이는 디바이스 공간 점을 지리 좌표 참조 시스템에 묶습니다. NextPDF Pro는 그 데이터를 불변 값 객체로부터 빌드합니다.

• GeoCoordinate — 위도/경도/고도 삼중값입니다. 구성 시 위도를 [-90, 90] 범위 내에서, 경도를 [-180, 180] 범위 내에서 검증하며, 도분초 및 십진 문자열 형식화를 제공합니다.
• GeoControlPoint — PDF 공간 점과 GeoCoordinate의 짝입니다.
• ProjectionType — 일반적인 투영법(지리, UTM, 횡축 메르카토르, 람베르트 정각 원추)의 enum이며, 각각 EPSG 코드로 매핑됩니다.
• GeoRegistration — 제어점과 더불어 투영 및 측지 기준계(기본 WGS84)입니다. isValid()는 최소 아핀 변환을 위해 최소 두 개의 제어점을 요구합니다. toPdfMeasureDictionary()는 /Subtype /GEO와 제어점 배열이 담긴 /Measure 딕셔너리를 방출합니다.

이렇게 동작하는 이유

NextPDF는 호출자가 제공한 원시 딕셔너리가 아니라 검증된 불변 값 객체로부터 measure 딕셔너리를 빌드합니다. GeoCoordinate는 구성 시 범위를 벗어난 위도나 경도를 거부합니다. GeoRegistration::isValid()는 두 개 미만의 제어점을 거부하므로, 잘못된 등록은 저하된 /GEO 딕셔너리를 방출하는 대신 빠르게 실패합니다. 투영법은 ProjectionType을 통해 표준 EPSG 코드로 해석되므로, 좌표 참조 시스템을 추측하지 않고 명시적으로 유지합니다. 기준계는 WGS84를 기본값으로 하되 명명된 필드로 남아 있으므로, 기본값이 아닌 참조 시스템은 의도적인 선택입니다. 이 fail-closed 자세가 중요한 이유는 잘못된 지리 참조가 아예 없는 것보다 더 나쁘기 때문입니다. 뷰어가 거짓 실세계 위치를 확신을 갖고 보고하게 됩니다. 설계 배경: 추측을 거부하는 API.

API 표면

클래스	책임
GeoCoordinate	형식화를 갖춘 검증된 위도/경도/고도입니다.
GeoControlPoint	PDF 점 ↔ 지리 점 짝입니다.
ProjectionType	EPSG 코드를 갖춘 투영 enum입니다.
GeoRegistration	/Measure /GEO 딕셔너리를 빌드합니다.

코드 샘플 — 빠른 시작

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

코드 샘플 — 프로덕션

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,
]);

엣지 케이스 및 함정

• GeoCoordinate 구성은 범위를 벗어난 위도나 경도를 거부합니다.
• 두 개 미만의 제어점은 유효하지 않은 등록을 생성합니다.
• 기본 기준계는 WGS84입니다. 다른 참조 시스템에는 명시적으로 설정하십시오.

성능

딕셔너리 생성은 제어점 수에 선형적입니다.

보안 참고

Geo 입력은 숫자 좌표 데이터입니다. 신뢰할 수 없는 입력에서 가져온 제어점은 등록하기 전에 검증하십시오.

적합성

동작	참조	상태
지리공간 measure 딕셔너리 (GEO 하위 유형)	ISO 32000-2 §12.8.2	부합 (의역됨)

동작 계약

• GeoCoordinate는 구성 시 위도를 [-90, 90] 범위 내에서, 경도를 [-180, 180] 범위 내에서 검증하며 DMS 및 십진 문자열 형식화를 제공합니다.
• GeoControlPoint는 PDF 공간 점을 GeoCoordinate와 짝짓습니다.
• GeoRegistration은 제어점과 더불어 (EPSG 코드로 매핑된) ProjectionType과 기본값이 WGS84인 측지 기준계를 담습니다. isValid()는 최소 두 개의 제어점을 요구합니다. toPdfMeasureDictionary()는 /Subtype /GEO와 제어점 배열이 담긴 /Measure 딕셔너리를 방출합니다.
• 범위를 벗어난 좌표나 두 개 미만의 제어점은 조용히 저하된 출력이 아니라 유효하지 않은 등록을 생성합니다.

Enterprise 경계 참고

Enterprise는 Geo 동작을 변경하지 않습니다. Enterprise는 별도로 문서화된 상위 등급 기능을 더합니다. 그것들은 GeoPDF measure 딕셔너리를 생성하는 데 필요하지 않습니다.

Core 폴백 / 대안

GeoPDF measure 딕셔너리 생성에 대한 Core 등가물은 없습니다. 이는 Pro 추가 기능입니다.

게시 경계

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 표, 런북 파일명, 티켓 접두사는 범위를 벗어납니다.

함께 보기

• Geo — 심층 참조 — 전체 클래스 및 메서드 참조.
• Document — 페이지 및 문서 조립.
• Core 주석.