Aspose.PDF FOSS
Developer Guide
Primitives

Primitives

Primitives

이 가이드는 API의 나머지 부분을 통해 기하학 및 색상 데이터를 전달하는 작고 실제로는 불변인 값 타입을 다룹니다: 2D 및 3D 포인트, 사각형, 변환 행렬, 색상 값. 간단한 워크플로우에서는 보통 이름으로 직접 가져오지 않습니다 — 주석, 이미지 배치, 3D 뷰와 같은 고수준 객체의 속성 타입으로 나타납니다 — 하지만 그 형태를 알면 해당 객체들의 속성을 읽고 구성하기가 쉬워집니다.

포인트: Point 및 Point3D

Point은 x 및 y 부동소수점 속성을 가진 단순 2D 좌표입니다. Point3D은 그 3D 대응물로, Point3D(x, y, z)로 구성되며 x, y, z 부동소수점 속성을 공개합니다. Point은 GradientAxialShading.start / end에 사용되는 타입이며; Matrix3D 기반 변환 및 3D 뷰는 Point3D가 설명하는 동일한 좌표 공간에서 작동합니다.

Rectangles

Rectangle(x, y, width, height)은 위치와 크기를 설명하며, 추가로 계산된 left, bottom, right 부동소수점 속성을 x, y, width, height와 함께 공개합니다. Rectangle은 PDF3DAnnotation.rect 뒤에 있는 타입으로, 따라서 3D 주석의 페이지 내 경계는 API의 다른 사각형과 동일한 형태를 통해 읽고 설정됩니다.

변환 행렬: Matrix 및 Matrix3D

Matrix은(는) 6개의 float 구성 요소 — a, b, c, d, e, f — 로 2D 어파인 변환을 보유하고 있으며 두 가지 메서드를 제공합니다: translate(x, y)은(는) 제자리에서 평행이동을 적용하고, multiply(other)은(는) 다른 Matrix와 합성하여 결과 Matrix을 반환합니다.

Matrix3D은(는) 3D 대응물로, 3x3 회전/스케일 블록(m11부터 m33까지)과 dx, dy, dz 번역 구성 요소를 포함합니다. 인자를 전혀 사용하지 않고(Matrix3D()) 생성되며 속성을 설정하여 채웁니다. PDF3DView.ctm은(는) Matrix3D | None 타입이며 — 저장된 3D 뷰의 현재 변환 행렬입니다.

팁 및 모범 사례

  • 문서에 명시된 순서(x, y[, z] / x, y, width, height)대로 위치 인자를 사용하여 Rectangle, Point, Point3D를 생성하십시오 — 이러한 타입은 키워드 전용 인자가 아니라 일반 float 값을 받습니다.
  • 수동으로 여섯 개의 a–f 구성 요소를 직접 결합하는 대신 Matrix.multiply()을 사용하여 변환을 합성하십시오.
  • 속성의 타입이 선택적일 때(예: PDF3DAnnotation.background_color: Color | None 또는 PDF3DView.ctm: Matrix3D | None), 중첩된 속성을 읽기 전에 None 여부를 확인하십시오.
  • 패턴 색 공간으로 두 색상의 선형 그라디언트가 필요할 때만 GradientAxialShading을 사용하십시오; 평면 단일 색상의 경우 Color을 직접 사용하십시오.
  • Rectangle의 left, bottom, right 속성은 x, y, width/height에서 파생됩니다 — 이를 별개의 상태가 아니라 동일한 사각형에 대한 편리한 뷰로 간주하십시오.

일반적인 문제

문제원인해결 방법
사각형 또는 점 좌표가 교환되었거나 잘못 스케일링된 것으로 보입니다위치 인수가 Rectangle(x, y, width, height) 또는 Point3D(x, y, z)에 잘못된 순서로 전달되었습니다생성자 시그니처와 비교하여 인수 순서를 다시 확인하십시오 — 이러한 유형은 키워드 전용 강제가 없습니다
AttributeError 색상 또는 매트릭스 속성을 읽을 때옵션 필드에서 None 값에 접근한 속성 (예: background_color, ctm)중첩된 속성에 접근하기 전에 값이 None가 아닌지 확인하십시오
그라디언트가 단일 평면 색상으로 렌더링됩니다GradientAxialShading.start와 end Point 값이 동일하거나 매우 가깝습니다start와 end이 의도된 그라디언트 축을 따라 시각적으로 구별되는 두 지점을 표시하도록 확인하십시오

FAQ

일반적인 사용 시 Point, Rectangle, 또는 Matrix를 직접 가져와야 하나요?

보통은 그렇지 않습니다 — 이러한 타입은 (PDF3DAnnotation.rect 또는 PDF3DView.ctm와 같은) 속성의 유형으로 가장 많이 마주치게 되며, 처음부터 직접 생성하는 경우는 드뭅니다. 다만 독립적인 값을 필요로 할 때 직접 생성하는 것을 막는 것은 없습니다.

Color와 ColorPrimitive의 차이점은 무엇인가요?

Color는 RGB 스타일 채널 데이터를 포함하고, 그라디언트 채우기를 위해 선택적인 pattern_color_space를 가집니다. ColorPrimitive는 훨씬 작은 타입으로, 오직 transparency 값만을 노출합니다.

Matrix를 사용하여 두 변환을 결합하려면 어떻게 해야 하나요?

matrix_a.multiply(matrix_b)를 호출하면 합성된 Matrix가 반환됩니다. 전체 매트릭스 곱셈을 만들지 않고 간단한 이동을 위해서는 translate(x, y)를 사용하십시오.

Matrix3D가 3D 주석 외의 다른 곳에서도 사용되나요?

이 클러스터 내에서 Matrix3D는 PDF3DView.ctm의 유형으로 나타납니다 — 저장된 3D 뷰와 연결된 현재 변환 행렬입니다.

API Reference 요약

클래스/메서드설명
Point2D 좌표 (x, y 실수 속성)
Point3D3D 좌표 (x, y, z float 속성)
Rectangle위치 및 크기 (x, y, width, height, 추가 계산된 left, bottom, right)
Matrix2D 어파인 변환 (a–f 구성 요소); translate / multiply 메서드
Matrix3D3D 변환 행렬 (m11–m33 회전/스케일 블록, dx/dy/dz translation)
Color옵션 pattern_color_space 그라디언트 채우기가 적용된 색상 값
ColorPrimitive최소 색상 프리미티브가 transparency를 노출함
GradientAxialShading두 Point 끝점을 따라 두 Color 값 사이의 축(선형) 그라디언트

참조

 한국어