3D Text
3D text is a text label at a given location with an orientation and size in 3D space that are maintained when zooming in and out. That is, it behaves like a 3D object.
The Text3D class represents a single 3D text label.
Text3D properties
All properties for 2D Text objects are applicable to 3D text objects. Additionally, use these properties to customise the look of your 3D text object:
| Set the direction of the label in space. The direction is defined from the start of the first character to the end of the last character. This property is a 3D vector [X, Y, Z]. | |
| Set the direction from the bottom of the text to the top. | |
| Set this boolean property to control whether the label should be visible or not when there are other 3D objects in front of the label. | |
|
Use this enum property to set where the text is facing. It can be set to the following values: |
Creating a Text3D object
from mapteksdk.project import Project
from mapteksdk.data import Text3D
project = Project() # Connect to default project
object_path = "scrapbook/text3d_example"
# Create Text
with project.new(object_path, Text3D, overwrite=True) as text:
text.text = 'hello world'
text.location = [0, 0, 0]
# Colours are R,G,B,A, where A is Alpha (255 = opaque)
text.colour = [38, 128, 0, 255] # Light Green
text.size = 100
Editing Text3D properties
The following example will modify the colour, size, text, and position of the text object created in the last example.
from mapteksdk.project import Project
project = Project() # Connect to default project
object_path = "scrapbook/text3d_example"
# Create Text
with project.edit(object_path) as text:
text.text = 'new text'
text.location = [50, 50, 50]
# Colours are R,G,B,A, where A is Alpha (255 = opaque)
text.colour = [255, 50, 50, 255]
text.size = 150
Labelling points at a particular height
The following example will add 3D text at each point, with its height, in any selected object that has point primitives.
from mapteksdk.project import Project
from mapteksdk.data import Text3D
import numpy as np
def colour_by_height(z_coordinates):
# Sets a basic colour map over points based on height value within height range
lowest, highest = np.min(z_coordinates), np.max(z_coordinates)
ratio = 2 * (z_coordinates - lowest) / (highest - lowest)
b = np.clip((255*(1-ratio)), 0, 255).astype(np.uint8)
r = np.clip((255*(ratio-1)), 0, 255).astype(np.uint8)
g = np.clip((255 - b - r), 0, 255).astype(np.uint8)
a = np.full(z_coordinates.shape, 255, dtype=np.uint8)
return np.column_stack((r,g,b,a))
project = Project() # Connect to default project
selection = project.get_selected()
for item in selection:
with project.read(item) as obj:
if hasattr(obj, 'points'):
# Append _facet_index_labels/ to the surface path as the container to
# store the text objects in
parent_path = f"{obj.id.path}_point_heights"
for i in range(obj.point_count):
# For convenience, get z coordinates as an array
z = obj.points[: ,2]
# Create colours to assign to each value based on height in range
colours = colour_by_height(z)
with project.new_or_edit(f"{parent_path}/{i}", Text3D, overwrite=True) as label:
# Position on the point
label.location = obj.points[i]
# Set label to point z coordinate
label.text = str(f"{round(z[i],1)}m")
label.size = 3
label.colour = colours[i]
Labelling point indices
The following example will add 3D text at each point, with its index position in the points array in any selected object that has point primitives.
from mapteksdk.project import Project
from mapteksdk.data import Text3D
project = Project() # Connect to default project
selection = project.get_selected()
for item in selection:
with project.read(item) as obj:
if hasattr(obj, 'points'): # Support anything with points
# Append _edge_index_labels/ to the surface path as the container to
# store the text objects in
parent_path = f"{obj.id.path}_point_index_labels"
for i in range(obj.point_count):
with project.new_or_edit(f"{parent_path}/{i}", Text3D, overwrite=True) as label:
# Position on the point
label.location = obj.points[i]
# Set label to point index
label.text = str(i)
label.size = 1
label.colour = [0, 255, 0, 255]
Labelling edge indices
The following example will add 3D text at the centre of each edge, with its index position in the edges array in any selected object that has edges primitives.
from mapteksdk.project import Project
from mapteksdk.data import Text3D
import numpy as np
def edge_distances(edge_lines:np.ndarray) -> np.ndarray:
# Calculate distance for each edge
p1, p2 = edge_lines[:, 0, :], edge_lines[:, 1, :]
line_lengths = np.sqrt((p2-p1)**2)
return np.sum(line_lengths, axis=1)
project = Project() # Connect to default project
selection = project.get_selected()
for item in selection:
with project.read(item) as obj:
if hasattr(obj, 'edges'): # Support lines or surfaces
# Append _edge_index_labels/ to the surface path as the container to
# store the text objects in
parent_path = f"{obj.id.path}_edge_index_labels"
edge_lines = obj.points[obj.edges]
edge_lengths = edge_distances(edge_lines)
edge_centres = np.mean(edge_lines, axis=1)
for i in range(edge_lines.shape[0]):
with project.new_or_edit(f"{parent_path}/{i}", Text3D, overwrite=True) as label:
# Position in the centre of the edge
label.location = edge_centres[i]
# Set label to edge index
label.text = str(i)
# Variably size the text based on the length of the edge
label.size = edge_lengths[i] / 10
label.colour = [255, 0, 0, 255]
Labelling facet indices
The following example will add 3D text at the centre of each facet, with its index position in the facets array in any selected Surface.
from mapteksdk.project import Project
from mapteksdk.data import Text3D, Surface
import numpy as np
def triangle_perimeters(triangles:np.ndarray) -> np.ndarray:
# Calculate perimeter for each triangle
p1, p2, p3 = triangles[:, 0, :], triangles[:, 1, :], triangles[:, 2, :]
line_lengths = np.sqrt((p2-p1)**2 + (p3-p2)**2 + (p3-p1)**2)
return np.sum(line_lengths, axis=1)
project = Project() # Connect to default project
selection = project.get_selected()
for item in selection:
if item.is_a(Surface):
with project.read(item) as surface:
# Append _facet_index_labels/ to the surface path as the container to
# store the text objects in
parent_path = f"{surface.id.path}_facet_index_labels"
triangles = surface.points[surface.facets]
perimiters = triangle_perimeters(triangles)
centroids = np.mean(triangles, axis=1)
for i in range(triangles.shape[0]):
with project.new_or_edit(f"{parent_path}/{i}", Text3D, overwrite=True) as label:
# Position in the centre of the facet
label.location = centroids[i]
# Set label to facet index
label.text = str(i)
# Variably size the text based on the perimeter of the facet
label.size = perimiters[i] / 15
