annotations.base

annotations.base

Classes

Name	Description
BaseAnnotation	Base class for an Annotation

BaseAnnotation

annotations.base.BaseAnnotation()

Base class for an Annotation

Any Entity that needs annotations support can derive from this base class for Entity specific annotations. The derived entity annotation will have to implement ‘init_subclass’ to register with the Entity’s annotation manager and ‘init’ to pass the entity to annotations.

Entity annotations will have to implement the ‘draw’ method that specifies how to display the annotations An optional ‘validate’ method can be provided to validate annotation inputs An optional ‘defaults’ method can be provided to set default values to the annotation.

Attributes

Name	Type	Description
name	str	Name (label) of the annotation
interface	AnnotationInterface	Dynamic interface of the annotation instance
viewport_width	int	Width of the viewport region in pixels
viewport_height	int	Height of the viewport region in pixels

Methods

Name	Description
defaults	Optional method to set default annotation params
distance	Distance between two vectors
draw	The main draw method for an annotation
draw_bmesh	Draw a Blender bmesh
draw_circle_3d	Draw a circle around a 3D point in the plane perpendicular to the
draw_cone	Draw a cone
draw_cylinder	Draw a cylinder
draw_line_2d	Draw a line between two points in 2D viewport space
draw_line_3d	Draw a line between two points in 3D space
draw_n_sided_cylinder	Draw an n sided cylinder
draw_n_sided_pyramid	Draw an n sided pyramid
draw_sphere	Draw a sphere
draw_text_2d	Draw text at a given 2D position (in pixels) of Viewport.
draw_text_2d_norm	Draw text at a given 2D position (normalized co-ordinates) of Viewport.
draw_text_3d	Draw text at a given 3D position
draw_triclinic_cell	Draw a triclinic box based on box vector lengths and angles
draw_wigner_seitz_cell	Draw a Wigner-Seitz cell from triclinic vectors
validate	Optional method to validate annotation inputs

defaults

annotations.base.BaseAnnotation.defaults()

Optional method to set default annotation params This is called only once when the annotation instance is created

distance

annotations.base.BaseAnnotation.distance(v1, v2)

Distance between two vectors

Parameters

Name	Type	Description	Default
v1	Vector	A 3D or 2D vector or tuple	required
v2	Vector	A 3D or 2D vector or tuple	required

Returns

Name	Type	Description
	Distance between the two vectors

draw

annotations.base.BaseAnnotation.draw()

The main draw method for an annotation This is called multiple times in the 3D viewport draw handler

draw_bmesh

annotations.base.BaseAnnotation.draw_bmesh(bm, overrides=None)

Draw a Blender bmesh

Parameters

Name	Type	Description	Default
bm	bmesh.types.BMesh	A bmesh object. A copy is made for internal use. Users will have to free the passed in object	required
overrides	dict	Optional dictionary to override common annotation params	None

draw_circle_3d

annotations.base.BaseAnnotation.draw_circle_3d(
    center,
    radius,
    normal,
    angle=360.0,
    start_dv=None,
    c_arrow=False,
    cc_arrow=False,
    overrides=None,
)

Draw a circle around a 3D point in the plane perpendicular to the given normal

Parameters

Name	Type	Description	Default
center	Vector	A 3D position vector of the center	required
radius	float	The radius of the circle	required
normal	Vector	The normal vector of the plane on which the cirle is to be drawn	required
angle	float	An angle less than 360 for partial circle (arc) - in degrees Default is 360 degrees	360.0
start_dv	Vector	The direction vector along which to start the circle (arc) If not provided, a random point in the plane perpendicular to the normal is chosen	None
c_arrow	bool	Whether to display clockwise arrow. Default is False	False
cc_arrow	bool	Whether to display counter clockwise arrow. Default is False	False
overrides	dict	Optional dictionary to override common annotation params	None

draw_cone

annotations.base.BaseAnnotation.draw_cone(
    location=(0, 0, 0),
    radius=1.0,
    height=1.0,
    axis=(0, 0, 1),
    cap_ends=True,
    overrides=None,
)

Draw a cone

Parameters

Name	Type	Description	Default
location	Vector	A 3D position vector of the base center	(0, 0, 0)
radius	float	Radius of the cone	1.0
height	float	Height of the cone	1.0
axis	Vector	Axis of the cone	(0, 0, 1)
cap_ends	bool	Whether to cap the base	True
overrides	dict	Optional dictionary to override common annotation params	None

draw_cylinder

annotations.base.BaseAnnotation.draw_cylinder(
    location=(0, 0, 0),
    radius=1.0,
    height=1.0,
    axis=(0, 0, 1),
    cap_ends=True,
    overrides=None,
)

Draw a cylinder

Parameters

Name	Type	Description	Default
location	Vector	A 3D position vector of the base center	(0, 0, 0)
radius	float	Radius of the cylinder	1.0
height	float	Height of the cylinder	1.0
axis	Vector	Axis of the cylinder	(0, 0, 1)
cap_ends	bool	Whether to cap the ends of cylinder	True
overrides	dict	Optional dictionary to override common annotation params	None

draw_line_2d

annotations.base.BaseAnnotation.draw_line_2d(
    v1,
    v2,
    v1_text=None,
    v2_text=None,
    mid_text=None,
    v1_arrow=False,
    v2_arrow=False,
    overrides=None,
)

Draw a line between two points in 2D viewport space

Parameters

Name	Type	Description	Default
v1	Vector	2D co-ordinates of the first point	required
v2	Vector	2D co-ordinates of the second point	required
v1_text	str	Optional text to display at v1	None
v2_text	str	Optional text to display at v2	None
mid_text	str	Optional text to display at the middle of the line	None
v1_arrow	bool	Whether to display an arrow at v1	False
v2_arrow	bool	Whether to display an arrow at v2	False
overrides	dict	Optional dictionary to override common annotation params	None

draw_line_3d

annotations.base.BaseAnnotation.draw_line_3d(
    v1,
    v2,
    v1_text=None,
    v2_text=None,
    mid_text=None,
    v1_arrow=False,
    v2_arrow=False,
    overrides=None,
)

Draw a line between two points in 3D space

Parameters

Name	Type	Description	Default
v1	Vector	3D co-ordinates of the first point	required
v2	Vector	3D co-ordinates of the second point	required
v1_text	str	Optional text to display at v1	None
v2_text	str	Optional text to display at v2	None
mid_text	str	Optional text to display at the middle of the line	None
v1_arrow	bool	Whether to display an arrow at v1	False
v2_arrow	bool	Whether to display an arrow at v2	False
overrides	dict	Optional dictionary to override common annotation params	None

draw_n_sided_cylinder

annotations.base.BaseAnnotation.draw_n_sided_cylinder(
    n=6,
    radius=10,
    height=10,
    origin=(0, 0, 0),
    axis=(0, 0, 1),
    cap_ends=True,
    overrides=None,
)

Draw an n sided cylinder Eg: square, rectangle, triangular prism, cube, cuboid, hexagonal cell etc

Parameters

Name	Type	Description	Default
n	int	Number of sides	6
radius	float	Radius of the cylinder	10
height	float	Height of the cylinder	10
origin	Vector	Center of the base of the cylinder	(0, 0, 0)
axis	Vector	Axis of the cylinder	(0, 0, 1)
cap_ends	bool	Whether to cap the ends of cylinder	True
overrides	dict	Optional dictionary to override common annotation params	None

draw_n_sided_pyramid

annotations.base.BaseAnnotation.draw_n_sided_pyramid(
    n=6,
    radius=10,
    height=10,
    origin=(0, 0, 0),
    axis=(0, 0, 1),
    cap_ends=True,
    overrides=None,
)

Draw an n sided pyramid Eg: triangle, prism, square pyramid, pentagonal pyramid, etc

Parameters

Name	Type	Description	Default
n	int	Number of sides	6
radius	float	Radius of the pyramid	10
height	float	Height of the pyramid	10
origin	Vector	Center of the base of the pyramid	(0, 0, 0)
axis	Vector	Axis of the pyramid	(0, 0, 1)
cap_ends	bool	Whether to cap the ends of pyramid	True
overrides	dict	Optional dictionary to override common annotation params	None

draw_sphere

annotations.base.BaseAnnotation.draw_sphere(
    location=(0, 0, 0),
    radius=1.0,
    overrides=None,
)

Draw a sphere

Parameters

Name	Type	Description	Default
location	Vector	A 3D position vector of the center	(0, 0, 0)
radius	float	Radius of the sphere	1.0
overrides	dict	Optional dictionary to override common annotation params	None

draw_text_2d

annotations.base.BaseAnnotation.draw_text_2d(pos_2d, text, overrides=None)

Draw text at a given 2D position (in pixels) of Viewport.

Parameters

Name	Type	Description	Default
pos_2d	Vector	Co-ordinates in pixels. (0, 0) is at bottom left	required
text	str	Text to display. ‘|’ as multi-line separator	required
overrides	dict	Optional dictionary to override common annotation params	None

draw_text_2d_norm

annotations.base.BaseAnnotation.draw_text_2d_norm(pos_2d, text, overrides=None)

Draw text at a given 2D position (normalized co-ordinates) of Viewport.

Parameters

Name	Type	Description	Default
pos_2d	Vector	Normalized co-ordinates (0 - 1). (0, 0) is at bottom left	required
text	str	Text to display. ‘|’ as multi-line separator	required
overrides	dict	Optional dictionary to override common annotation params	None

draw_text_3d

annotations.base.BaseAnnotation.draw_text_3d(pos_3d, text, overrides=None)

Draw text at a given 3D position

Parameters

Name	Type	Description	Default
pos_3d	Vector	Co-ordinates in 3D world space (x, y, z)	required
text	str	Text to display. ‘|’ as multi-line separator	required
overrides	dict	Optional dictionary to override common annotation params	None

draw_triclinic_cell

annotations.base.BaseAnnotation.draw_triclinic_cell(
    a=10.0,
    b=10.0,
    c=10.0,
    alpha=90.0,
    beta=90.0,
    gamma=90.0,
    origin=(0, 0, 0),
    show_lattice=False,
    overrides=None,
)

Draw a triclinic box based on box vector lengths and angles

Parameters

Name	Type	Description	Default
a	float	Box vector a length	10.0
b	float	Box vector b length	10.0
c	float	Box vector c length	10.0
alpha	float	Angle between box vectors bc	90.0
beta	float	Angle between box vectors ac	90.0
gamma	float	Angle between box vectors ab	90.0
origin	Vector	Origin of the box	(0, 0, 0)
show_lattice	bool	Whether to show a 3x3x3 lattice	False
overrides	dict	Optional dictionary to override common annotation params	None

draw_wigner_seitz_cell

annotations.base.BaseAnnotation.draw_wigner_seitz_cell(
    triclinic_vectors,
    center_to_origin=False,
    show_lattice=False,
    overrides=None,
)

Draw a Wigner-Seitz cell from triclinic vectors

Parameters

Name	Type	Description	Default
triclinic_vectors	npt.ArrayLike	Vectors that represent the base triclinic cell	required
center_to_origin	bool	Move the center of the cell to origin (0, 0, 0)	False
show_lattice	bool	Whether to show a 3x3x3 lattice	False
overrides	dict	Optional dictionary to override common annotation params	None

validate

annotations.base.BaseAnnotation.validate()

Optional method to validate annotation inputs This is called during annotation creation and any time the inputs change either through the API or GUI. Can return False or raise an exception when validation fails. Returns True when all validations succeed.

Note: This method gets called when any inputs change, so updating values in here will lead to a recursive loop and should not be done.