Geo — 심층 참조

한눈에 보기

이 페이지는 NextPDF Pro Geo 모듈의 계약 수준 참조입니다. 노출 표면은 네 개의 불변 값 객체 — GeoCoordinate, GeoControlPoint, ProjectionType, GeoRegistration — 와, 등록을 페이지 인덱스와 연결하고 뷰포트 출력을 방출하는 GeoPdfLayer로 구성됩니다. 이 모듈은 PDF 딕셔너리 텍스트를 생성합니다: /Subtype /GEO를 갖춘 /Measure 딕셔너리, /Viewport 딕셔너리, 그리고 페이지 수준의 /VP 배열 값입니다. 생성은 결정론적 문자열 조립이며, 네트워크 호출도, 파일시스템 접근도, 무작위성도 없습니다. 이 페이지는 공개 API, 관찰 가능한 동작 계약, 그리고 실패 모드를 기술합니다.

가용성 및 라이선스

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

이 모듈을 게이트하는 기능별 라이선스 플래그는 없습니다. Geo 클래스는 nextpdf/pro가 설치되어 있으면 언제든지 사용할 수 있습니다.

공개 API 표면

심볼	매개변수	기본 동작	반환	던지거나 실패하는 조건	비고
GeoCoordinate	생성자: float $latitude, float $longitude, float $altitude = 0.0	위도가 [-90, 90] 안에, 경도가 [-180, 180] 안에 있는지 검증	—	둘 중 하나라도 범위를 벗어나면 InvalidArgumentException	final readonly; 고도는 해수면 위 미터 값이며 범위 검증되지 않음
GeoCoordinate::toDms()	없음	N/S 및 E/W 접미사를 붙여 도-분-초로 포맷	string	—	0에 가까운 초는 00으로 렌더링; 그 외에는 소수점 두 자리로 하고 후행 0을 제거
GeoCoordinate::toDecimal()	없음	위도와 경도를 소수점 여섯 자리로, 쉼표로 구분하여 포맷	string	—	고도는 포함되지 않음
GeoCoordinate::fromDms()	string $dms	DMS 문자열을 파싱; 초는 선택 사항; 타이포그래피 도 기호와 인용 부호 글리프를 정규화	self	문자열이 파싱되지 않거나 파싱된 값이 생성자 범위 검증에 실패할 때 InvalidArgumentException	정적 팩토리; 반구 문자는 대소문자 구분 없음; 고도는 기본값 0.0
GeoControlPoint	생성자: float $pdfX, float $pdfY, GeoCoordinate $geo	PDF 사용자 공간 점(포인트)을 지리 좌표와 짝지음	—	—	final readonly; PDF 좌표는 검증되지 않음
ProjectionType	문자열 기반 열거형, 4개 케이스	케이스: Geographic, UTM, TransverseMercator, LambertConformal	기반 값 GEO, UTM, TM, LCC	—	아래 투영 매핑 표 참조
ProjectionType::epsgCode()	없음	케이스를 하나의 고정 EPSG 코드로 매핑	int	—	4326, 32601, 2154, 또는 3347
ProjectionType::label()	없음	사람이 읽을 수 있는 투영 이름	string	—	예: WGS 84 Geographic
GeoRegistration	생성자: array $controlPoints, ProjectionType $projection, string $datum = 'WGS84'	제어점, 투영, 측지 데이텀을 담음	—	—	final readonly; 제어점 개수는 생성 시 검증되지 않음
GeoRegistration::isValid()	없음	제어점이 최소 두 개일 것을 요구	bool	—	두 점은 아핀 매핑을 위한 최소값
GeoRegistration::toPdfMeasureDictionary()	없음	/Subtype /GEO, /GCS, /GPTS, /LPTS, /Bounds를 갖춘 /Measure 딕셔너리를 방출	string	—	isValid()를 확인하지 않음; 호출을 보호하거나 GeoPdfLayer를 경유할 것
GeoPdfLayer::addRegistration()	int $pageIndex, GeoRegistration $registration	0 기반 페이지 인덱스에 대한 등록을 추가	self	$pageIndex가 음수일 때 InvalidArgumentException	플루언트; 한 페이지에 처음 추가된 등록이 생성 시점에 우선함
GeoPdfLayer::getRegistrations()	없음	모든 등록을 삽입 순서대로 반환	list<array{pageIndex: int, registration: GeoRegistration}>	—	추가된 대로 중복 및 유효하지 않은 등록도 포함
GeoPdfLayer::generateViewportDictionary()	int $pageIndex	/BBox, /Name, 인라인 /Measure를 갖춘 /Viewport 딕셔너리를 방출	string	—	페이지에 등록이 없거나 등록이 유효하지 않으면 빈 문자열
GeoPdfLayer::generateViewportArray()	int $pageIndex	뷰포트 딕셔너리를 대괄호로 감싸 /VP 배열 리터럴로 만듦	string	—	없으면 빈 문자열; 호출자는 해당 페이지에 대해 /VP를 생략함
GeoPdfLayer::writeToPdfWriter()	BinaryBuffer $buffer, int $pageIndex	/VP 와 배열 리터럴, 그리고 줄바꿈을 버퍼에 씀	bool	—	항목이 작성되었을 때 true; 그 외에는 무동작이며 false

진입점 시그니처

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

동작 계약

좌표 검증 및 포맷팅

GeoCoordinate는 생성 시 검증하며 결코 변경되지 않습니다. [-90, 90]을 벗어난 위도 또는 [-180, 180]을 벗어난 경도는 위반 값을 명시하는 InvalidArgumentException을 던집니다. toDms()는 두 축을 도, 0으로 채운 분, 초, 그리고 반구 접미사로 렌더링합니다. toDecimal()은 latitude, longitude를 소수점 여섯 자리로 렌더링합니다. fromDms()는 초가 선택적인 DMS 입력을 받아들이고, 프라임·이중 프라임·도 기호·스마트 인용 부호 글리프를 정규화하며, 부호 있는 십진 도로 변환한 뒤 새 인스턴스를 구성합니다. 남위와 서경은 음수 값이 됩니다.

투영 매핑

각 ProjectionType 케이스는 하나의 고정 EPSG 코드와 레이블을 지닙니다. 이 매핑은 닫힌 표이며, 좌표 참조 시스템 레지스트리가 아닙니다.

케이스	기반 값	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

UTM 케이스는 zone 1 코드를 방출합니다. 다른 UTM 존이나 이 표 밖의 EPSG 코드가 필요한 프로젝트는 권위 있는 CRS 설명을 datum 문자열에 Well Known Text로 담아야 합니다.

Measure 딕셔너리 방출

GeoRegistration::toPdfMeasureDictionary()는 여러 줄의 딕셔너리를 방출합니다: /Type /Measure, /Subtype /GEO, /GCS 좌표계 딕셔너리, /GPTS, /LPTS, /Bounds이며, ISO 32000-2:2020 §12.10(Table 269)을 따릅니다. 구체적 동작은 다음과 같습니다:

• /GCS는 << /Type /PROJCS /EPSG <code> /WKT (<datum>) >>로 방출됩니다. EPSG 코드는 투영 케이스에서 나옵니다. /WKT 값은 공급된 그대로의 datum 문자열이며, 기본값은 WGS84입니다.
• /GPTS는 위도-경도 쌍을 소수점 여섯 자리로, 제어점 순서대로 나열합니다.
• /LPTS는 pdfX/pdfY 쌍을 공급된 그대로 소수점 여섯 자리로 나열합니다. ISO 32000-2:2020 Table 269은 LPTS 점을 2D 단위 정사각형 안에 정의하며, 단위 정사각형으로 정규화된 값을 공급하는 것은 호출자의 책임입니다.
• /Bounds는 전체 단위 정사각형인 [0 0 0 1 1 1 1 0]으로 고정됩니다.
• datum 문자열은 리터럴 문자열로 보간되기 전에 이스케이프됩니다: 백슬래시, 괄호, 일반적인 제어 문자는 ISO 32000-2:2020 §7.3.4.2에 따라 백슬래시 이스케이프가 됩니다. 호출자의 영향을 받은 datum은 리터럴 문자열을 종료하거나 원시 PDF 토큰을 주입할 수 없습니다.

뷰포트 및 페이지 방출

GeoPdfLayer는 등록을 0 기반 페이지 인덱스로 키를 지정하여 삽입 순서대로 유지합니다. generateViewportDictionary()는 요청된 페이지에 대한 첫 번째 등록을 확인하며, 등록이 없거나 isValid()가 false이면 빈 문자열을 반환합니다. 생성된 딕셔너리는 /Type /Viewport, 최소 및 최대 제어점 PDF 좌표에서 계산된 /BBox, GeoViewport_Page<n> 형태의 /Name, 그리고 인라인 /Measure 딕셔너리를 지닙니다. 뷰포트 /Measure 항목은 ISO 32000-2:2020 §12.9를 따릅니다. generateViewportArray()는 딕셔너리를 대괄호로 감싸 페이지 /VP 값을 만들어 내며, 이는 ISO 32000-2:2020 §7.7.3.3(Table 31)에 따른 뷰포트 딕셔너리의 배열입니다. writeToPdfWriter()는 /VP 와 배열 리터럴을 Core BinaryBuffer에 쓰고 무언가가 작성되었는지를 보고하므로, 페이지 직렬화가 해당 키를 깔끔하게 생략할 수 있습니다.

예외 상황 및 실패 모드

• 범위를 벗어난 위도 또는 경도는 생성 시 InvalidArgumentException을 던집니다. 부분적으로 유효한 좌표는 존재하지 않습니다.
• fromDms()는 파싱할 수 없는 입력에 대해 던집니다. 파싱된 값은 생성자를 통과하므로, 구문적으로 유효하지만 값이 범위를 벗어난 문자열도 던집니다.
• DMS 표기법은 고도를 담지 않으므로, fromDms()는 항상 고도 0.0을 산출합니다.
• 제어점이 두 개 미만인 GeoRegistration은 isValid()가 false를 보고하지만, toPdfMeasureDictionary()는 여전히 짧은 점 배열을 갖춘 딕셔너리를 방출합니다. 직접 호출은 isValid()로 보호하거나, 유효하지 않은 등록을 억제하는 GeoPdfLayer를 경유하십시오.
• 한 페이지 인덱스에 대한 중복 등록은 getRegistrations()에 의해 모두 유지되며, 뷰포트 생성은 처음 추가된 것을 사용합니다.
• 음수 페이지 인덱스는 InvalidArgumentException을 던집니다. 페이지 인덱스는 0 기반입니다.
• X 또는 Y 값을 공유하는 제어점은 폭이 0이거나 높이가 0인 퇴화된 /BBox를 만듭니다. 두 축에 걸쳐 있는 점을 공급하십시오.
• 모든 출력은 생성된 텍스트입니다. 디스크나 네트워크에는 아무것도 쓰이지 않으며, 동일한 입력은 동일한 출력을 만듭니다.
• 이 모듈에서는 어떠한 암호화 연산도 발생하지 않으므로, FIPS 모드 고유의 동작은 없습니다.

적합성

주장	표준	절
measure 딕셔너리는 subtype GEO로, GPTS 위도-경도 쌍과 짝지어진 LPTS 값과 함께 방출된다.	ISO 32000-2:2020	§12.10
뷰포트 딕셔너리는 BBox, Name, Measure 항목을 지닌다.	ISO 32000-2:2020	§12.9
페이지 VP 값은 뷰포트 딕셔너리의 배열로 방출된다.	ISO 32000-2:2020	§7.7.3.3
datum 보간은 리터럴 문자열 메타문자를 이스케이프한다.	ISO 32000-2:2020	§7.3.4.2

모든 절은 의역된 것이며, NextPDF는 규범 텍스트를 재현하지 않습니다. 이는 기능 진술이지 인증이 아닙니다. NextPDF는 어떠한 인증도 보유하지 않으며 부여하지도 않습니다. EPSG 코드는 투영 케이스별 고정된 대표 값이고, /WKT 항목은 생성된 Well Known Text 설명이 아니라 공급된 datum 문자열을 담으며, 두 진술 모두 제품에 근거합니다. 뷰어 측 측정에 의존하기 전에, 대상 인터랙티브 PDF 프로세서에서 방출된 GeoPDF 출력을 검증하십시오.

개발 노트

• nextpdf/pro 1.9.0부터 제공; nextpdf/pro 3.1.0에서 현재 유효합니다.
• toPdfMeasureDictionary()를 직접 호출하기 전에 isValid()를 확인하십시오. GeoPdfLayer가 이 확인을 대신 수행합니다.
• 다운스트림 소비자가 /WKT를 파싱할 때는 완전한 Well Known Text 설명을 datum으로 전달하십시오. 기본값 WGS84는 datum 레이블일 뿐입니다.
• 뷰포트 경계가 PDF 공간 값과 다를 때는 제어점을 구성하기 전에 LPTS 입력을 단위 정사각형으로 정규화하십시오.
• 방출 비용은 제어점 개수에 선형이고, GeoPdfLayer의 조회는 등록 개수에 선형입니다.
• writeToPdfWriter()는 Core의 NextPDF\Support\BinaryBuffer를 통해 페이지 직렬화와 통합됩니다.

발행 경계

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

함께 보기

• Geo (기능) — 설치, 개념 개요, 빠른 시작 샘플.
• Document — 심층 참조 — 문서 및 페이지 구성 표면.