Primitives

Primitives

Este guia cobre os pequenos tipos de valor, imutáveis na prática, que transportam dados de geometria e cor através do restante do API: pontos 2D e 3D, retângulos, matrizes de transformação e valores de cor. Normalmente você não importará esses tipos diretamente pelo nome em fluxos de trabalho simples — eles aparecem como tipos de propriedade em objetos de nível superior, como anotações, posicionamentos de imagem e visualizações 3D — mas conhecer sua estrutura facilita a leitura e a construção das propriedades desses objetos.

Pontos: Point e Point3D

Point é uma coordenada 2D simples com propriedades float x e y. Point3D é sua contraparte 3D, construída como Point3D(x, y, z) e expondo as propriedades float x, y e z. Point é o tipo usado para GradientAxialShading.start / end; transformações baseadas em Matrix3D e visualizações 3D operam no mesmo espaço de coordenadas que Point3D descreve.

Rectangles

Rectangle(x, y, width, height) descreve uma posição e tamanho, e ainda expõe as propriedades float calculadas left, bottom e right junto com x, y, width e height. Rectangle é o tipo por trás de PDF3DAnnotation.rect, portanto os limites na página de uma anotação 3D são lidos e definidos através da mesma forma que qualquer outro retângulo no API.

Matrizes de Transformação: Matrix e Matrix3D

Matrix contém uma transformação afim 2D como seis componentes de ponto flutuante — a, b, c, d, e, f — e fornece dois métodos: translate(x, y) para aplicar uma translação in-place, e multiply(other) para compô-lo com outro Matrix, retornando o Matrix resultante.

Matrix3D é a contraparte 3D: um bloco de rotação/escala 3x3 (m11 até m33) mais um componente de translação dx, dy, dz, construído sem argumentos (Matrix3D()) e preenchido definindo suas propriedades. PDF3DView.ctm tem tipo Matrix3D | None — a matriz de transformação atual para uma visualização 3D salva.

Dicas e Melhores Práticas

• Construa Rectangle, Point e Point3D com argumentos posicionais na ordem documentada (x, y[, z] / x, y, width, height) — esses tipos aceitam floats simples, não argumentos apenas por palavra-chave.
• Use Matrix.multiply() para compor transformações ao invés de combinar manualmente os seis componentes a–f à mão.
• Quando o tipo de uma propriedade é opcional (por exemplo PDF3DAnnotation.background_color: Color | None ou PDF3DView.ctm: Matrix3D | None), verifique None antes de ler propriedades aninhadas nela.
• Recorra a GradientAxialShading somente quando precisar de um gradiente linear de duas cores como espaço de cor de padrão; para uma cor plana e única, use Color diretamente.
• As propriedades left, bottom e right de Rectangle são derivadas de x, y e width/height — trate-as como uma visualização de conveniência do mesmo retângulo, e não como estado independente.

Problemas Comuns

FAQ

Preciso importar Point, Rectangle ou Matrix diretamente no uso normal?

Normalmente não — você geralmente encontrará esses como o tipo de uma propriedade (como PDF3DAnnotation.rect ou PDF3DView.ctm) ao invés de construí-los do zero, embora nada impeça construí-los diretamente quando precisar de um valor independente.

Qual é a diferença entre Color e ColorPrimitive?

Color contém dados de canal no estilo RGB mais um pattern_color_space opcional para preenchimentos de gradiente. ColorPrimitive é um tipo muito menor que expõe apenas um valor transparency.

Como combinar duas transformações com Matrix?

Chame matrix_a.multiply(matrix_b), que retorna o Matrix composto. Use translate(x, y) para uma translação simples sem construir uma multiplicação completa de matriz.

O Matrix3D é usado em algum lugar fora das anotações 3D?

Dentro deste cluster, Matrix3D aparece como o tipo de PDF3DView.ctm — a matriz de transformação atual associada a uma visualização 3D salva.

API Reference Resumo

Ver também

• Aspose.PDF for Python — Enterprise Documentation