Primitives

Primitives

Esta guía cubre los tipos de valor pequeños, inmutables en la práctica, que transportan datos de geometría y color a través del resto del API: puntos 2D y 3D, rectángulos, matrices de transformación y valores de color. Normalmente no los importas directamente por nombre en flujos de trabajo simples — aparecen como tipos de propiedad en objetos de nivel superior como anotaciones, colocaciones de imágenes y vistas 3D — pero conocer su forma facilita la lectura y construcción de las propiedades de esos objetos.

Puntos: Point y Point3D

Point es una coordenada 2D simple con propiedades flotantes x y y. Point3D es su contraparte 3D, construida como Point3D(x, y, z) y que expone las propiedades flotantes x, y y z. Point es el tipo usado para GradientAxialShading.start / end; las transformaciones basadas en Matrix3D y las vistas 3D operan en el mismo espacio de coordenadas que describe Point3D.

Rectangles

Rectangle(x, y, width, height) describe una posición y un tamaño, y además expone las propiedades flotantes calculadas left, bottom y right junto con x, y, width y height. Rectangle es el tipo detrás de PDF3DAnnotation.rect, por lo que los límites en la página de una anotación 3D se leen y establecen mediante la misma forma que cualquier otro rectángulo en el API.

Matrices de Transformación: Matrix y Matrix3D

Matrix contiene una transformación afín 2D como seis componentes de punto flotante — a, b, c, d, e, f — y proporciona dos métodos: translate(x, y) para aplicar una traslación in situ, y multiply(other) para componerla con otro Matrix, devolviendo el Matrix resultante.

Matrix3D es la contraparte 3D: un bloque de rotación/escala 3x3 (m11 a m33) más un componente de traslación dx, dy, dz, construido sin argumentos (Matrix3D()) y rellenado estableciendo sus propiedades. PDF3DView.ctm tiene tipo Matrix3D | None — la matriz de transformación actual para una vista 3D guardada.

Consejos y Mejores Prácticas

• Construya Rectangle, Point y Point3D con argumentos posicionales en el orden documentado (x, y[, z] / x, y, width, height) — estos tipos aceptan flotantes simples, no argumentos solo por palabra clave.
• Utilice Matrix.multiply() para componer transformaciones en lugar de combinar manualmente los seis componentes a–f a mano.
• Cuando el tipo de una propiedad es opcional (por ejemplo PDF3DAnnotation.background_color: Color | None o PDF3DView.ctm: Matrix3D | None), verifique None antes de leer propiedades anidadas en ella.
• Utilice GradientAxialShading solo cuando necesite un degradado lineal de dos colores como espacio de color de patrón; para un color plano y único use Color directamente.
• Las propiedades left, bottom y right de Rectangle se derivan de x, y y width/height — considérelas como una vista de conveniencia del mismo rectángulo en lugar de un estado independiente.

Problemas comunes

FAQ

¿Necesito importar Point, Rectangle o Matrix directamente en el uso normal?

Generalmente no — lo encontrarás más a menudo como el tipo de una propiedad (como PDF3DAnnotation.rect o PDF3DView.ctm) en lugar de construirlos desde cero, aunque nada impide construirlos directamente cuando necesitas un valor independiente.

¿Cuál es la diferencia entre Color y ColorPrimitive?

Color lleva datos de canales al estilo RGB más un pattern_color_space opcional para rellenos de degradado. ColorPrimitive es un tipo mucho más pequeño que expone solo un valor transparency.

¿Cómo combino dos transformaciones con Matrix?

Llama a matrix_a.multiply(matrix_b), que devuelve el Matrix compuesto. Usa translate(x, y) para una traslación simple sin construir una multiplicación completa de matrices.

¿Se utiliza Matrix3D en alguna parte fuera de las anotaciones 3D?

Dentro de este clúster, Matrix3D aparece como el tipo de PDF3DView.ctm — la matriz de transformación actual asociada a una vista 3D guardada.

API Reference Resumen

Ver también

• Aspose.PDF for Python — Enterprise Documentation