entities.molecule.annotations

entities.molecule.annotations

Classes

Name	Description
Label2D	Common Label2D Annotation for all entities
Label3D	Common Label3D Annotation for all entities
MoleculeAnnotation	Base class for a Molecule Annotation
MoleculeAnnotationManager	Annotation Manager for Molecule Entity
MoleculeInfo	Molecule Info Annotation

Label2D

entities.molecule.annotations.Label2D()

Common Label2D Annotation for all entities

Label3D

entities.molecule.annotations.Label3D()

Common Label3D Annotation for all entities

MoleculeAnnotation

entities.molecule.annotations.MoleculeAnnotation(molecule)

Base class for a Molecule Annotation

All molecule annotations should derive from this base class and implement the ‘draw’ method. All derived classes will have access to the molecule instance (self.molecule) and all the annotation inputs and common params via self.interface.

An optional ‘defaults’ method can be provided to set default values to the annotation.

Attributes

Name	Description
viewport_height	Get the viewport region height in pixels
viewport_width	Get the viewport region width 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

entities.molecule.annotations.MoleculeAnnotation.defaults()

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

distance

entities.molecule.annotations.MoleculeAnnotation.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

entities.molecule.annotations.MoleculeAnnotation.draw()

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

draw_bmesh

entities.molecule.annotations.MoleculeAnnotation.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

entities.molecule.annotations.MoleculeAnnotation.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

entities.molecule.annotations.MoleculeAnnotation.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

entities.molecule.annotations.MoleculeAnnotation.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

entities.molecule.annotations.MoleculeAnnotation.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

entities.molecule.annotations.MoleculeAnnotation.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

entities.molecule.annotations.MoleculeAnnotation.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

entities.molecule.annotations.MoleculeAnnotation.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

entities.molecule.annotations.MoleculeAnnotation.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

entities.molecule.annotations.MoleculeAnnotation.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

entities.molecule.annotations.MoleculeAnnotation.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

entities.molecule.annotations.MoleculeAnnotation.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

entities.molecule.annotations.MoleculeAnnotation.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

entities.molecule.annotations.MoleculeAnnotation.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

entities.molecule.annotations.MoleculeAnnotation.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.

MoleculeAnnotationManager

entities.molecule.annotations.MoleculeAnnotationManager(entity)

Annotation Manager for Molecule Entity

Attributes

Name	Description
visible	Visibility of all annotations - getter

Methods

Name	Description
clear	Remove all annotations
get	Get an annotation by name
register	Register an annotation class
remove	Remove an annotation by name or instance
unregister	Unregister a registered annotation class

clear

entities.molecule.annotations.MoleculeAnnotationManager.clear()

Remove all annotations

get

entities.molecule.annotations.MoleculeAnnotationManager.get(name)

Get an annotation by name

register

entities.molecule.annotations.MoleculeAnnotationManager.register(
    annotation_class,
)

This method adds the annotation class to the entity specific class registry (classes) and adds a new method (add) to the manager with a signature that matches the annotation inputs.

remove

entities.molecule.annotations.MoleculeAnnotationManager.remove(annotation)

Remove an annotation by name or instance

When a name is used, all annotations that match the name will be removed

unregister

entities.molecule.annotations.MoleculeAnnotationManager.unregister(
    annotation_class,
)

Unregister a registered annotation class

This method removes the annotation class from the entity speicific class registry and removes the ‘add_<>’ method from the manager

MoleculeInfo

entities.molecule.annotations.MoleculeInfo(molecule)

Molecule Info Annotation

Attributes

Name	Type	Description
location	tuple[float, float]	Normalized coordinates (0.0 - 1.0) of the postion in viewport / render
show_models	bool	Whether or not to show the number of models in the molecule
show_atoms	bool	Whether or not to show the number of atoms in the molecule
custom_text	str	Any custom text to add at the end of the annotation

Methods

Name	Description
distance	Distance between two vectors
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

distance

entities.molecule.annotations.MoleculeInfo.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_bmesh

entities.molecule.annotations.MoleculeInfo.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

entities.molecule.annotations.MoleculeInfo.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

entities.molecule.annotations.MoleculeInfo.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

entities.molecule.annotations.MoleculeInfo.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

entities.molecule.annotations.MoleculeInfo.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

entities.molecule.annotations.MoleculeInfo.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

entities.molecule.annotations.MoleculeInfo.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

entities.molecule.annotations.MoleculeInfo.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

entities.molecule.annotations.MoleculeInfo.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

entities.molecule.annotations.MoleculeInfo.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

entities.molecule.annotations.MoleculeInfo.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

entities.molecule.annotations.MoleculeInfo.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

entities.molecule.annotations.MoleculeInfo.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

entities.molecule.annotations.MoleculeInfo.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`