Text
Module: digi21.base
Text at specified coordinates, inheriting from Geometry.
Text(text, coordinates, codes=(), rotation=0.0, text_height=1.0,
text_justification=TextJustification.SW, orientation=(1.0, 0.0, 0.0, 0.0))
| Argument | Type | Description |
|---|---|---|
text |
str |
Text string |
coordinates |
tuple |
(x, y, z) coordinates |
codes |
iterable | Codes |
rotation |
float |
Rotation in degrees, counterclockwise from X |
text_height |
float |
Text height |
text_justification |
TextJustification | Justification |
orientation |
tuple |
Spatial text orientation: (w, x, y, z) quaternion. Defaults to the XY plane. See Spatial orientation |
Properties
| Property | Type | R/W | Description |
|---|---|---|---|
text |
str |
R/W | Text string |
height |
float |
R/W | Text height |
rotation |
float |
R/W | Text rotation in degrees, counterclockwise from X around world Z. Applied after orientation. Earlier versions used hundredths of a degree |
orientation |
tuple |
R/W | Spatial text orientation: (w, x, y, z) quaternion applied before rotation. Normalized on assignment. See Spatial orientation |
justification |
TextJustification | R/W | Text justification |
Also inherits all Geometry properties and methods.
Spatial orientation
A rotation quaternion is four numbers (w, x, y, z) representing a spatial rotation. Rotation by θ around unit direction vector (ux, uy, uz) is (cos(θ/2), ux·sin(θ/2), uy·sin(θ/2), uz·sin(θ/2)).
Full text rotation is Rz(rotation) · Q, where Q is the orientation quaternion and Rz(rotation) rotates rotation degrees around world Z. Q applies first in text local coordinates; Rz(rotation) then applies to its result. In text local coordinates, X follows the baseline supporting the characters, Y points toward their top, and Z points toward the reader.
orientation |
Text position |
|---|---|
(1, 0, 0, 0) |
XY plane (default). Full rotation is just rotation |
(cos 45°, sin 45°, 0, 0) |
Vertical plane with horizontal baseline: 90° rotation around X. With rotation = 0, the baseline follows world X, character tops point toward positive Z, and the readable face points toward negative Y. Other rotation values set the baseline horizontal angle from X |
When assigning orientation or passing orientation to the constructor:
- The stored quaternion is normalized by dividing all four components by √(w² + x² + y² + z²). Thus
(1, 1, 0, 0)equals(cos 45°, sin 45°, 0, 0). If the norm differs from 1 by at most 10⁻¹², it is stored unchanged. - Zero, infinite, or NaN norms store
(1.0, 0.0, 0.0, 0.0). Examples include(0, 0, 0, 0)and any quaternion with an infinite or NaN component. rotationis unchanged. Assigningrotationlikewise leavesorientationunchanged.- For text belonging to the drawing, assignment raises
ValueError, as with other properties: drawing geometries are read-only.
orientation returns four float values. Without an orientation constructor argument, it returns (1.0, 0.0, 0.0, 0.0). Quaternions q and -q represent the same rotation; orientation retains the assigned sign. A clone() has the original orientation.
Horizontal direction belongs in rotation
Set rotation to the horizontal baseline direction and use orientation only to tilt text out of XY without rotation around Z. For facade text with a 30° horizontal baseline, use rotation = 30 and orientation = (cos 45°, sin 45°, 0, 0), rather than rotation = 0 with a quaternion including the 30° turn. Digi3D.AI commands and DWG/DXF, DGN, and GeoMedia importers always store text this way.
Both forms look identical, but text retains its assigned quaternion without transferring Z rotation to rotation. With a quaternion rotating around Z:
rotationis not the horizontal text direction. Settingrotation = agives baseline angleaplus the quaternion own horizontal baseline angle.- Formats storing only rotation (BIN, VEC, GeoJSON, PDF) use the
rotationdirection. See Text orientation in drawing files. - XY text with a quaternion rotating only around Z counts as oriented. BIND stores it in
Digi21.DigiNG.Text2, which earlier Digi3D versions cannot load.
Example
from digi21.base import Text, TextJustification
t = Text("Calle Mayor", (50, 60, 0), codes=["ROT"],
text_height=2.5, text_justification=TextJustification.C)
Create vertical text with a baseline 30° from horizontal X:
from digi21.base import Text
# Normalized (1, 1, 0, 0) is (cos 45°, sin 45°, 0, 0): a 90° rotation around X.
fachada = Text("Fachada", (50, 60, 12), codes=["ROT"], rotation=30.0,
text_height=2.5, orientation=(1, 1, 0, 0))
print(fachada.orientation) # (0.7071067811865475, 0.7071067811865475, 0.0, 0.0)
See also
- TextJustification
- Geometry
- CAMERA_ORIENTED_TEXT: when enabled, TEXT, 1TEXT, EDITABLE_TEXT, TEXT_R, and EDITABLE_TEXT_R spatially orient inserted text