CMLibs Utils

The CMLibs Utils is a collection of Python utilities to support working with the Zinc library. This package provides six modules

geometry.plane
zinc.field
zinc.finiteelement
zinc.general
zinc.material
image

These modules are surfaced under the namespace package cmlibs within the utils package. To use these modules the following import statement can be used:

import cmlibs.utils.geometry.plane
import cmlibs.utils.zinc.finiteelement

Geometry

The geometry package contains a module plane. The plane module encapsulates describing a plane (a point and a normal vector) in a Zinc way. It also encapsulates a way to serialise a description of a plane.

Zinc

The zinc package is made up of four modules. The modules are aimed at raising the API level of the Zinc library making it easier to perform common tasks. The field module deals with creating and querying fields. The finiteelement module deals with creating finite elements. This includes creating nodes and querying node extents. The general module makes available Python Context Managers for Zinc objects that send messages. The material module add functionality to create a material from an image field.

Image

The image module contains a function for extracting the coordinates of the corners of a DICOM image.

Package API

Geometry Package

Plane

class cmlibs.utils.geometry.plane.PlaneAttitude(point, normal): A class to help serialise and compare Plane attitudes.

class cmlibs.utils.geometry.plane.ZincPlane(fieldmodule): A description of a plane in Zinc terms. The plane is described by a 3D point and a normal vector.

Zinc Package

Field

Utilities for creating and working with Zinc Fields.

cmlibs.utils.zinc.field.assignFieldParameters(target_field: Field, source_field: Field): Copy parameters from sourceField to targetField. Currently only works for node parameters.

cmlibs.utils.zinc.field.assign_field_parameters(target_field: Field, source_field: Field): Copy parameters from sourceField to targetField. Currently only works for node parameters.

cmlibs.utils.zinc.field.createFieldCoordinates(fieldmodule: Fieldmodule, name='coordinates', components_count=3, managed=False) → FieldFiniteElement: Create RC coordinates finite element field of supplied name with number of components 1, 2, or 3 and the components named “x”, “y” and “z” if used. New field is not managed by default.

cmlibs.utils.zinc.field.createFieldEulerAnglesRotationMatrix(fieldmodule: Fieldmodule, euler_angles: Field) → Field: From Zinc graphics_library.cpp, matrix transposed to row major. Matrix is product RzRyRx, giving rotation about x, then y, then z with positive angles rotating by right hand rule about axis. :param fieldmodule: The fieldmodule to create the field in. :param euler_angles: 3-component field of angles in radians, components: 0 = azimuth (about z) 1 = elevation (about y) 2 = roll (about x) :return: 3x3 rotation matrix field suitable for pre-multiplying vector v i.e. v’ = Mv

cmlibs.utils.zinc.field.createFieldFibres(fieldmodule: Fieldmodule, name='fibres', components_count=3, managed=False) → FieldFiniteElement

Finds or creates a finite element fibre field. New field has component names: “fibre angle”, “imbrication angle”, “sheet angle”. New field is not managed by default.

Parameters:

fieldmodule – Zinc fieldmodule to find or create field in.
name – Name of field to find or create.
components_count – Number of components of field, from 1 to 3.
managed – Managed state of field if created here.

Returns:

Zinc FieldFiniteElement

cmlibs.utils.zinc.field.createFieldFiniteElementClone(source_field: Field, name: str, managed=False) → FieldFiniteElement: Copy an existing Finite Element Field to a new field of supplied name. Note: does not handle time-varying parameters. New field is not managed by default. :param source_field: Zinc finite element field to copy. :param name: The name of the new field, asserts that no field of that name exists. :param managed: Managed state of field created here. :return: New identically defined field with supplied name.

cmlibs.utils.zinc.field.createFieldGroup(fieldmodule: Fieldmodule, name: str, managed=False) → FieldGroup

Finds or creates a Group field of the supplied name. New field is not managed by default.

Parameters:

fieldmodule – Zinc fieldmodule to find or create field in.
name – Name of field to find or create.
managed – Managed state of field if created here.

Returns:

Zinc FieldGroup.

cmlibs.utils.zinc.field.createFieldImage(fieldmodule, image_filename, name='image')

Create an image field using the given fieldmodule. The image filename must exist and be a known image type.

Parameters:

fieldmodule – The fieldmodule to create the field in.
image_filename – Image filename.
name – Optional name of the image field, defaults to ‘image’.

Returns:

The image field created.

cmlibs.utils.zinc.field.createFieldIsoScalarForPlane(fieldmodule: Fieldmodule, coordinate_field, plane): Create iso-scalar field for use with plane. :param fieldmodule: Fieldmodule to own new field. :param coordinate_field: :param plane: Plane description object.

cmlibs.utils.zinc.field.createFieldMeshIntegral(coordinates: Field, mesh: Mesh, number_of_points=3): Create a field integrating the coordinates to give scalar volume/area/length over the mesh, depending on its dimension. :param coordinates: :param mesh: :param number_of_points: Number of Gauss points. :return: Field giving volume of coordinates field over mesh via Gaussian quadrature.

cmlibs.utils.zinc.field.createFieldPlaneVisibility(fieldmodule, finite_element_field, plane_normal_field, point_on_plane_field): Create a visibility field that is based on the plane equation.

cmlibs.utils.zinc.field.createFieldStoredMeshLocation(fieldmodule: Fieldmodule, mesh: Mesh, name=None, managed=False) → FieldStoredMeshLocation

Create a stored mesh location field for storing locations in the supplied mesh, used for storing data projections. New field is not managed by default.

Parameters:

fieldmodule – Zinc fieldmodule to find or create field in.
mesh – Mesh to store locations in, from same fieldmodule.
name – Name of new field. If not defined, defaults to “location_” + mesh.getName().
managed – Managed state of field.

Returns:

Zinc FieldStoredMeshLocation

cmlibs.utils.zinc.field.createFieldStoredString(fieldmodule: Fieldmodule, name='name', managed=False) → Field

Creates a stored string field for defining names on nodes or datapoints. New field is not managed by default.

Parameters:

fieldmodule – Zinc fieldmodule to find or create field in.
name – Name of field to find or create.
managed – Managed state of field if created here.

Returns:

Zinc Field.

cmlibs.utils.zinc.field.createFieldTextureCoordinates(fieldmodule: Fieldmodule, name='texture coordinates', components_count=3, managed=False) → FieldFiniteElement: Create texture coordinates finite element field of supplied name with number of components 1, 2, or 3 and the components named “u”, “v” and “w” if used. New field is not managed by default.

cmlibs.utils.zinc.field.createFieldVisibilityForPlane(fieldmodule: Fieldmodule, coordinate_field, plane): Create a visibility field for a plane. :param fieldmodule: Fieldmodule to own new field. :param coordinate_field: :param plane: :return:

cmlibs.utils.zinc.field.createFieldVolumeImage(fieldmodule, image_filenames, name='volume_image')

Create an image field using the given fieldmodule. The image filename must exist and be a known image type.

Parameters:

fieldmodule – The fieldmodule to create the field in.
image_filenames – Image filename.
name – Optional name of the image field, defaults to ‘volume_image’.

Returns:

The image field created.

cmlibs.utils.zinc.field.createFieldsDisplacementGradients(coordinates: Field, reference_coordinates: Field, mesh: Mesh)

Returns:: 1st and 2nd displacement gradients of (coordinates - referenceCoordinates) w.r.t. referenceCoordinates.

cmlibs.utils.zinc.field.createFieldsTransformations(coordinates: Field, rotation_angles=None, scale_value=1.0, translation_offsets=None)

Create constant fields for rotation, scale and translation containing the supplied values, plus the transformed coordinates applying them in the supplied order.

See create_field_euler_angles_rotation_matrix.

Parameters:

coordinates – The coordinate field to scale, 3 components.
rotation_angles – List of euler angles, length = number of components.
scale_value – Scalar to multiply all components of coordinates.
translation_offsets – List of offsets, length = number of components.

Returns:

4 fields: transformedCoordinates, rotation, scale, translation

cmlibs.utils.zinc.field.create_field_coordinates(fieldmodule: Fieldmodule, name='coordinates', components_count=3, managed=False) → FieldFiniteElement: Create RC coordinates finite element field of supplied name with number of components 1, 2, or 3 and the components named “x”, “y” and “z” if used. New field is not managed by default.

cmlibs.utils.zinc.field.create_field_euler_angles_rotation_matrix(fieldmodule: Fieldmodule, euler_angles: Field) → Field: From Zinc graphics_library.cpp, matrix transposed to row major. Matrix is product RzRyRx, giving rotation about x, then y, then z with positive angles rotating by right hand rule about axis. :param fieldmodule: The fieldmodule to create the field in. :param euler_angles: 3-component field of angles in radians, components: 0 = azimuth (about z) 1 = elevation (about y) 2 = roll (about x) :return: 3x3 rotation matrix field suitable for pre-multiplying vector v i.e. v’ = Mv

cmlibs.utils.zinc.field.create_field_fibres(fieldmodule: Fieldmodule, name='fibres', components_count=3, managed=False) → FieldFiniteElement

Finds or creates a finite element fibre field. New field has component names: “fibre angle”, “imbrication angle”, “sheet angle”. New field is not managed by default.

Parameters:

fieldmodule – Zinc fieldmodule to find or create field in.
name – Name of field to find or create.
components_count – Number of components of field, from 1 to 3.
managed – Managed state of field if created here.

Returns:

Zinc FieldFiniteElement

cmlibs.utils.zinc.field.create_field_finite_element_clone(source_field: Field, name: str, managed=False) → FieldFiniteElement: Copy an existing Finite Element Field to a new field of supplied name. Note: does not handle time-varying parameters. New field is not managed by default. :param source_field: Zinc finite element field to copy. :param name: The name of the new field, asserts that no field of that name exists. :param managed: Managed state of field created here. :return: New identically defined field with supplied name.

cmlibs.utils.zinc.field.create_field_group(fieldmodule: Fieldmodule, name: str, managed=False) → FieldGroup

Finds or creates a Group field of the supplied name. New field is not managed by default.

Parameters:

fieldmodule – Zinc fieldmodule to find or create field in.
name – Name of field to find or create.
managed – Managed state of field if created here.

Returns:

Zinc FieldGroup.

cmlibs.utils.zinc.field.create_field_image(fieldmodule, image_filename, name='image')

Create an image field using the given fieldmodule. The image filename must exist and be a known image type.

Parameters:

fieldmodule – The fieldmodule to create the field in.
image_filename – Image filename.
name – Optional name of the image field, defaults to ‘image’.

Returns:

The image field created.

cmlibs.utils.zinc.field.create_field_iso_scalar_for_plane(fieldmodule: Fieldmodule, coordinate_field, plane): Create iso-scalar field for use with plane. :param fieldmodule: Fieldmodule to own new field. :param coordinate_field: :param plane: Plane description object.

cmlibs.utils.zinc.field.create_field_mesh_integral(coordinates: Field, mesh: Mesh, number_of_points=3): Create a field integrating the coordinates to give scalar volume/area/length over the mesh, depending on its dimension. :param coordinates: :param mesh: :param number_of_points: Number of Gauss points. :return: Field giving volume of coordinates field over mesh via Gaussian quadrature.

cmlibs.utils.zinc.field.create_field_plane_visibility(fieldmodule, finite_element_field, plane_normal_field, point_on_plane_field): Create a visibility field that is based on the plane equation.

cmlibs.utils.zinc.field.create_field_stored_mesh_location(fieldmodule: Fieldmodule, mesh: Mesh, name=None, managed=False) → FieldStoredMeshLocation

Create a stored mesh location field for storing locations in the supplied mesh, used for storing data projections. New field is not managed by default.

Parameters:

fieldmodule – Zinc fieldmodule to find or create field in.
mesh – Mesh to store locations in, from same fieldmodule.
name – Name of new field. If not defined, defaults to “location_” + mesh.getName().
managed – Managed state of field.

Returns:

Zinc FieldStoredMeshLocation

cmlibs.utils.zinc.field.create_field_stored_string(fieldmodule: Fieldmodule, name='name', managed=False) → Field

Creates a stored string field for defining names on nodes or datapoints. New field is not managed by default.

Parameters:

fieldmodule – Zinc fieldmodule to find or create field in.
name – Name of field to find or create.
managed – Managed state of field if created here.

Returns:

Zinc Field.

cmlibs.utils.zinc.field.create_field_texture_coordinates(fieldmodule: Fieldmodule, name='texture coordinates', components_count=3, managed=False) → FieldFiniteElement: Create texture coordinates finite element field of supplied name with number of components 1, 2, or 3 and the components named “u”, “v” and “w” if used. New field is not managed by default.

cmlibs.utils.zinc.field.create_field_visibility_for_plane(fieldmodule: Fieldmodule, coordinate_field, plane): Create a visibility field for a plane. :param fieldmodule: Fieldmodule to own new field. :param coordinate_field: :param plane: :return:

cmlibs.utils.zinc.field.create_field_volume_image(fieldmodule, image_filenames, name='volume_image')

Create an image field using the given fieldmodule. The image filename must exist and be a known image type.

Parameters:

fieldmodule – The fieldmodule to create the field in.
image_filenames – Image filename.
name – Optional name of the image field, defaults to ‘volume_image’.

Returns:

The image field created.

cmlibs.utils.zinc.field.create_fields_displacement_gradients(coordinates: Field, reference_coordinates: Field, mesh: Mesh)

Returns:: 1st and 2nd displacement gradients of (coordinates - referenceCoordinates) w.r.t. referenceCoordinates.

cmlibs.utils.zinc.field.create_fields_transformations(coordinates: Field, rotation_angles=None, scale_value=1.0, translation_offsets=None)

Create constant fields for rotation, scale and translation containing the supplied values, plus the transformed coordinates applying them in the supplied order.

See create_field_euler_angles_rotation_matrix.

Parameters:

coordinates – The coordinate field to scale, 3 components.
rotation_angles – List of euler angles, length = number of components.
scale_value – Scalar to multiply all components of coordinates.
translation_offsets – List of offsets, length = number of components.

Returns:

4 fields: transformedCoordinates, rotation, scale, translation

cmlibs.utils.zinc.field.determine_node_field_derivatives(region, coordinates, include_versions=False): Create Node Value fields for each node derivative. Expensive as needs to query parameters across nodes. :param region: Region coordinates field belongs to. :param coordinates: Finite element field to query. :param include_versions: Set to True to search for versions above 1, False to return version 1 only. :return: List over node derivatives D1, D2, D12, D3, D13, D23, D123 of list of Node Value fields giving the derivative value for either version 1 or versions 1..N of those parameters at any node.

cmlibs.utils.zinc.field.fieldExists(fieldmodule: Fieldmodule, name: str, field_type, components_count) → bool

Tests to determine if the field with the given name exists in the given field module.

Parameters:

fieldmodule – Zinc field module to search.
name – Name of field to find.
field_type – Type of field if derived type. Default: finiteelement.
components_count – Number of components in the field. Default: 3.

Returns:

True if the field is found in the module with the given name and number of components, false otherwise.

cmlibs.utils.zinc.field.fieldIsManagedCoordinates(field_in: Field): Conditional function returning True if the field is Finite Element type, with coordinate type attribute, up to 3 components, and is managed.

cmlibs.utils.zinc.field.fieldIsManagedGroup(field_in: Field): Conditional function returning True if the field is a managed Group.

cmlibs.utils.zinc.field.field_exists(fieldmodule: Fieldmodule, name: str, field_type, components_count) → bool

Tests to determine if the field with the given name exists in the given field module.

Parameters:

fieldmodule – Zinc field module to search.
name – Name of field to find.
field_type – Type of field if derived type. Default: finiteelement.
components_count – Number of components in the field. Default: 3.

Returns:

True if the field is found in the module with the given name and number of components, false otherwise.

cmlibs.utils.zinc.field.field_is_managed_coordinates(field_in: Field): Conditional function returning True if the field is Finite Element type, with coordinate type attribute, up to 3 components, and is managed.

cmlibs.utils.zinc.field.field_is_managed_group(field_in: Field): Conditional function returning True if the field is a managed Group.

cmlibs.utils.zinc.field.field_is_managed_real_1_to_3_components(field_in: Field): Conditional function returning True if the field is real-valued with up to 3 components, and is managed. Used e.g. for choosing a fibre field.

cmlibs.utils.zinc.field.findOrCreateFieldCoordinates(fieldmodule: Fieldmodule, name='coordinates', components_count=3, managed=True) → FieldFiniteElement: Get or create RC coordinates finite element field of supplied name with number of components 1, 2, or 3 and the components named “x”, “y” and “z” if used. New field is managed by default.

cmlibs.utils.zinc.field.findOrCreateFieldFibres(fieldmodule: Fieldmodule, name='fibres', components_count=3, managed=True) → FieldFiniteElement

Finds or creates a finite element fibre field. New field has component names: “fibre angle”, “imbrication angle”, “sheet angle”. New field is managed by default.

Parameters:

fieldmodule – Zinc fieldmodule to find or create field in.
name – Name of field to find or create.
components_count – Number of components of field, from 1 to 3.
managed – Managed state of field if created here.

Returns:

Zinc FieldFiniteElement

cmlibs.utils.zinc.field.findOrCreateFieldFiniteElement(fieldmodule: Fieldmodule, name: str, components_count: int, component_names=None, managed=False, type_coordinate=False) → FieldFiniteElement

Finds or creates a finite element field for the specified number of real components.

Parameters:

fieldmodule – Zinc Fieldmodule to find or create field in.
name – Name of field to find or create.
components_count – Number of components / dimension of field, from 1 to 3.
component_names – Optional list of component names.
managed – Managed state of field if created here.
type_coordinate – Default value of flag indicating field gives geometric coordinates.

Returns:

Zinc FieldFiniteElement, invalid if error.

cmlibs.utils.zinc.field.findOrCreateFieldGroup(fieldmodule: Fieldmodule, name: str, managed=True) → FieldGroup

Finds or creates a Group field of the supplied name. New field is managed by default.

Parameters:

fieldmodule – Zinc fieldmodule to find or create field in.
name – Name of field to find or create.
managed – Managed state of field if created here.

Returns:

Zinc FieldGroup.

cmlibs.utils.zinc.field.findOrCreateFieldStoredMeshLocation(fieldmodule: Fieldmodule, mesh: Mesh, name=None, managed=True) → FieldStoredMeshLocation

Get or create a stored mesh location field for storing locations in the supplied mesh, used for storing data projections. Note can’t currently verify existing field stores locations in the supplied mesh. New field is managed by default.

Parameters:

fieldmodule – Zinc fieldmodule to find or create field in.
mesh – Mesh to store locations in, from same fieldmodule.
name – Name of new field. If not defined, defaults to “location_” + mesh.getName().
managed – Managed state of field if created here.

cmlibs.utils.zinc.field.findOrCreateFieldStoredString(fieldmodule: Fieldmodule, name='name', managed=True) → Field

Finds or creates a stored string field for defining names on nodes or datapoints. Note can’t use Field.castStoredString API as not released. New field is managed by default.

Parameters:

fieldmodule – Zinc fieldmodule to find or create field in.
name – Name of field to find or create.
managed – Managed state of field if created here.

Returns:

Zinc Field.

cmlibs.utils.zinc.field.findOrCreateFieldTextureCoordinates(fieldmodule: Fieldmodule, name='texture coordinates', components_count=3, managed=True) → FieldFiniteElement: Create texture coordinates finite element field of supplied name with number of components 1, 2, or 3 and the components named “u”, “v” and “w” if used. New field is managed by default.

cmlibs.utils.zinc.field.find_or_create_field_coordinates(fieldmodule: Fieldmodule, name='coordinates', components_count=3, managed=True) → FieldFiniteElement: Get or create RC coordinates finite element field of supplied name with number of components 1, 2, or 3 and the components named “x”, “y” and “z” if used. New field is managed by default.

cmlibs.utils.zinc.field.find_or_create_field_fibres(fieldmodule: Fieldmodule, name='fibres', components_count=3, managed=True) → FieldFiniteElement

Finds or creates a finite element fibre field. New field has component names: “fibre angle”, “imbrication angle”, “sheet angle”. New field is managed by default.

Parameters:

fieldmodule – Zinc fieldmodule to find or create field in.
name – Name of field to find or create.
components_count – Number of components of field, from 1 to 3.
managed – Managed state of field if created here.

Returns:

Zinc FieldFiniteElement

cmlibs.utils.zinc.field.find_or_create_field_finite_element(fieldmodule: Fieldmodule, name: str, components_count: int, component_names=None, managed=False, type_coordinate=False) → FieldFiniteElement

Finds or creates a finite element field for the specified number of real components.

Parameters:

fieldmodule – Zinc Fieldmodule to find or create field in.
name – Name of field to find or create.
components_count – Number of components / dimension of field, from 1 to 3.
component_names – Optional list of component names.
managed – Managed state of field if created here.
type_coordinate – Default value of flag indicating field gives geometric coordinates.

Returns:

Zinc FieldFiniteElement, invalid if error.

cmlibs.utils.zinc.field.find_or_create_field_group(fieldmodule: Fieldmodule, name: str, managed=True) → FieldGroup

Finds or creates a Group field of the supplied name. New field is managed by default.

Parameters:

fieldmodule – Zinc fieldmodule to find or create field in.
name – Name of field to find or create.
managed – Managed state of field if created here.

Returns:

Zinc FieldGroup.

cmlibs.utils.zinc.field.find_or_create_field_stored_mesh_location(fieldmodule: Fieldmodule, mesh: Mesh, name=None, managed=True) → FieldStoredMeshLocation

Get or create a stored mesh location field for storing locations in the supplied mesh, used for storing data projections. Note can’t currently verify existing field stores locations in the supplied mesh. New field is managed by default.

Parameters:

fieldmodule – Zinc fieldmodule to find or create field in.
mesh – Mesh to store locations in, from same fieldmodule.
name – Name of new field. If not defined, defaults to “location_” + mesh.getName().
managed – Managed state of field if created here.

cmlibs.utils.zinc.field.find_or_create_field_stored_string(fieldmodule: Fieldmodule, name='name', managed=True) → Field

Finds or creates a stored string field for defining names on nodes or datapoints. Note can’t use Field.castStoredString API as not released. New field is managed by default.

Parameters:

fieldmodule – Zinc fieldmodule to find or create field in.
name – Name of field to find or create.
managed – Managed state of field if created here.

Returns:

Zinc Field.

cmlibs.utils.zinc.field.find_or_create_field_texture_coordinates(fieldmodule: Fieldmodule, name='texture coordinates', components_count=3, managed=True) → FieldFiniteElement: Create texture coordinates finite element field of supplied name with number of components 1, 2, or 3 and the components named “u”, “v” and “w” if used. New field is managed by default.

cmlibs.utils.zinc.field.getGroupList(fieldmodule): Get list of Zinc groups (FieldGroup) in fieldmodule.

cmlibs.utils.zinc.field.getManagedFieldNames(fieldmodule): Get names of managed fields in fieldmodule.

cmlibs.utils.zinc.field.getUniqueFieldName(fieldmodule: Fieldmodule, name: str) → str

Return a unique field name in fieldmodule either equal to name or appending a number starting at 1 and increasing.

Parameters:

fieldmodule – The fieldmodule to get a unique name in.
name – The name to match or append a number to.

cmlibs.utils.zinc.field.get_group_list(fieldmodule): Get list of Zinc groups (FieldGroup) in fieldmodule.

cmlibs.utils.zinc.field.get_managed_field_names(fieldmodule): Get names of managed fields in fieldmodule.

cmlibs.utils.zinc.field.get_unique_field_name(fieldmodule: Fieldmodule, name: str) → str

Return a unique field name in fieldmodule either equal to name or appending a number starting at 1 and increasing.

Parameters:

fieldmodule – The fieldmodule to get a unique name in.
name – The name to match or append a number to.

cmlibs.utils.zinc.field.orphanFieldByName(fieldmodule: Fieldmodule, name: str): Find existing field with the name in fieldmodule. If it exists, uniquely rename it (prefix with “.destroy_” and append unique number) and unmanage it so destroyed when no longer in use.

cmlibs.utils.zinc.field.orphan_field_by_name(fieldmodule: Fieldmodule, name: str): Find existing field with the name in fieldmodule. If it exists, uniquely rename it (prefix with “.destroy_” and append unique number) and unmanage it so destroyed when no longer in use.

FiniteElement

Utilities for creating and working with Zinc Finite Elements.

cmlibs.utils.zinc.finiteelement.createCubeElement(mesh: Mesh, finite_element_field: Field, node_coordinate_set)

Create a single finite element using the supplied finite element field and sequence of 8 n-D node coordinates.

Parameters:

mesh – The Zinc Mesh to create elements in.
finite_element_field – Zinc FieldFiniteElement to interpolate on element.
node_coordinate_set – Sequence of 8 coordinates each with as many components as finite element field.

Returns:

None

cmlibs.utils.zinc.finiteelement.createLineElement(mesh: Mesh, finite_element_field: Field, node_coordinate_set)

Create a single linear 1-D finite element using the supplied finite element field and sequence of 2 n-D node coordinates.

Parameters:

mesh – The Zinc Mesh to create elements in.
finite_element_field – Zinc FieldFiniteElement to interpolate on element.
node_coordinate_set – Sequence of 4 coordinates each with as many components as finite element field.

Returns:

None

cmlibs.utils.zinc.finiteelement.createNodes(finite_element_field, node_coordinate_set, node_set_name='nodes', time=None, node_set=None)

Create a node for every coordinate in the node_coordinate_set.

Parameters:

finite_element_field – Finite element field to assign node coordinates to.
node_coordinate_set – A list of node coordinates of the same dimension as the finite element field.
node_set_name – The name of the nodeset to create the node in, either ‘nodes’ (default) or ‘datapoints’.
time – The time to set for the node, defaults to None for nodes that are not time aware.
node_set – The node set to use for creating nodes, if not set then the node set for creating nodes is chosen by node_set_name.

Returns:

A list of nodes.

cmlibs.utils.zinc.finiteelement.createSquareElement(mesh: Mesh, finite_element_field: Field, node_coordinate_set)

Create a single square 2-D finite element using the supplied finite element field and sequence of 4 n-D node coordinates.

Parameters:

mesh – The Zinc Mesh to create elements in.
finite_element_field – Zinc FieldFiniteElement to interpolate on element.
node_coordinate_set – Sequence of 4 coordinates each with as many components as finite element field.

Returns:

None

cmlibs.utils.zinc.finiteelement.createTriangleElements(mesh: Mesh, finite_element_field: Field, element_node_set)

Create a linear triangular element for every set of 3 local nodes in element_node_set.

Parameters:

mesh – The Zinc Mesh to create elements in.
finite_element_field – Zinc FieldFiniteElement to interpolate from nodes.
element_node_set – Sequence of 3 node identifiers for each element.

Returns:

None

cmlibs.utils.zinc.finiteelement.create_cube_element(mesh: Mesh, finite_element_field: Field, node_coordinate_set)

Create a single finite element using the supplied finite element field and sequence of 8 n-D node coordinates.

Parameters:

mesh – The Zinc Mesh to create elements in.
finite_element_field – Zinc FieldFiniteElement to interpolate on element.
node_coordinate_set – Sequence of 8 coordinates each with as many components as finite element field.

Returns:

None

cmlibs.utils.zinc.finiteelement.create_line_element(mesh: Mesh, finite_element_field: Field, node_coordinate_set)

Create a single linear 1-D finite element using the supplied finite element field and sequence of 2 n-D node coordinates.

Parameters:

mesh – The Zinc Mesh to create elements in.
finite_element_field – Zinc FieldFiniteElement to interpolate on element.
node_coordinate_set – Sequence of 4 coordinates each with as many components as finite element field.

Returns:

None

cmlibs.utils.zinc.finiteelement.create_nodes(finite_element_field, node_coordinate_set, node_set_name='nodes', time=None, node_set=None)

Create a node for every coordinate in the node_coordinate_set.

Parameters:

finite_element_field – Finite element field to assign node coordinates to.
node_coordinate_set – A list of node coordinates of the same dimension as the finite element field.
node_set_name – The name of the nodeset to create the node in, either ‘nodes’ (default) or ‘datapoints’.
time – The time to set for the node, defaults to None for nodes that are not time aware.
node_set – The node set to use for creating nodes, if not set then the node set for creating nodes is chosen by node_set_name.

Returns:

A list of nodes.

cmlibs.utils.zinc.finiteelement.create_square_element(mesh: Mesh, finite_element_field: Field, node_coordinate_set)

Create a single square 2-D finite element using the supplied finite element field and sequence of 4 n-D node coordinates.

Parameters:

mesh – The Zinc Mesh to create elements in.
finite_element_field – Zinc FieldFiniteElement to interpolate on element.
node_coordinate_set – Sequence of 4 coordinates each with as many components as finite element field.

Returns:

None

cmlibs.utils.zinc.finiteelement.create_triangle_elements(mesh: Mesh, finite_element_field: Field, element_node_set)

Create a linear triangular element for every set of 3 local nodes in element_node_set.

Parameters:

mesh – The Zinc Mesh to create elements in.
finite_element_field – Zinc FieldFiniteElement to interpolate from nodes.
element_node_set – Sequence of 3 node identifiers for each element.

Returns:

None

cmlibs.utils.zinc.finiteelement.evaluateFieldNodesetMean(field: Field, nodeset: Nodeset)

Returns:: Mean of field over nodeset, or None if invalid.

cmlibs.utils.zinc.finiteelement.evaluateFieldNodesetRange(field: Field, nodeset: Nodeset)

Returns:: min, max range of field over nodes, or None, None if invalid.

cmlibs.utils.zinc.finiteelement.evaluate_field_mesh_integral(field: Field, coordinate_field: Field, mesh: Mesh, number_of_integration_points=4): Integrate value of a field over mesh using Gaussian Quadrature. :param field: Field to integrate over mesh. Must be real valued. :param coordinate_field: Field giving spatial coordinates to integrate over. Must be real-valued with number of components equal or greater than mesh dimension, up to a maximum of 3. :param mesh: The mesh or mesh group to integrate over. :param number_of_integration_points: Number of integration points in each element direction. :return: Integral value, or None if undefined.

cmlibs.utils.zinc.finiteelement.evaluate_field_nodeset_mean(field: Field, nodeset: Nodeset)

Returns:: Mean of field over nodeset, or None if invalid.

cmlibs.utils.zinc.finiteelement.evaluate_field_nodeset_range(field: Field, nodeset: Nodeset)

Returns:: min, max range of field over nodes, or None, None if invalid.

cmlibs.utils.zinc.finiteelement.evaluate_mesh_centroid(coordinates: Field, mesh: Mesh, number_of_integration_points=4): Get the centroid of the coordinate field over mesh. :param coordinates: Field giving spatial coordinates to integrate over. Must be real-valued with number of components equal or greater than mesh dimension, up to a maximum of 3. :param mesh: The mesh or mesh group to integrate over. :param number_of_integration_points: Number of integration points in each element direction. :return: Centroid coordinates, or None if empty group or field not defined.

cmlibs.utils.zinc.finiteelement.evaluate_nearest_mesh_location(start_coordinates, coordinate_field: Field, mesh: Mesh, is_exterior=False, is_on_face=0): Evaluate mesh location where coordinate field is nearest to start coordinates. If the model has elements of dimension greater than 1, optionally restrict to exterior and/or specified face type. :param start_coordinates: Start coordinates as float (1-D) or list of float (n-D). :param coordinate_field: Field giving spatial coordinates over mesh. Must be real-valued with number of components equal or greater than mesh dimension, up to a maximum of 3. :param mesh: The mesh or mesh group to search. :param is_exterior: Optional flag: if True restrict search to faces of mesh on exterior of model. :param is_on_face: Optional element face type, to restrict search to faces of mesh with specified face type. :return: Nearest Element, xi or None, None if undefined.

cmlibs.utils.zinc.finiteelement.findNodeWithName(nodeset: Nodeset, name_field: Field, name: str, ignore_case=False, strip_whitespace=False): Get single node in nodeset with supplied name. :param nodeset: Zinc Nodeset or NodesetGroup to search. :param name_field: The name field to match. :param name: The name to match in nameField. :param ignore_case: Set to True to ignore case differences. :param strip_whitespace: Set to True to ignore leading and trailing whitespace differences. :return: Zinc Node with name, or None if 0 or multiple nodes with name.

cmlibs.utils.zinc.finiteelement.find_node_with_name(nodeset: Nodeset, name_field: Field, name: str, ignore_case=False, strip_whitespace=False): Get single node in nodeset with supplied name. :param nodeset: Zinc Nodeset or NodesetGroup to search. :param name_field: The name field to match. :param name: The name to match in nameField. :param ignore_case: Set to True to ignore case differences. :param strip_whitespace: Set to True to ignore leading and trailing whitespace differences. :return: Zinc Node with name, or None if 0 or multiple nodes with name.

cmlibs.utils.zinc.finiteelement.getElementNodeIdentifiers(element: Element, eft: Elementfieldtemplate) → list

Get list of node identifiers used by eft in element in the order for eft.

Parameters:

element – The element to query.
eft – The element field template the nodes are mapped for.

Returns:

List of global node identifiers.

cmlibs.utils.zinc.finiteelement.getElementNodeIdentifiersBasisOrder(element: Element, eft: Elementfieldtemplate) → list

Get list of node identifiers used by eft in element with the default number and order for the element basis. For example, with a bilinear lagrange basis, 4 node identifiers are always returned, possibly with repeats, even if the eft collapsed it to 3 nodes in an arbitrary order.

Parameters:

element – The element to query.
eft – The element field template the nodes are mapped for.

Returns:

List of global node identifiers.

cmlibs.utils.zinc.finiteelement.getMaximumElementIdentifier(mesh: Mesh) → int

Returns:: Maximum element identifier in mesh or -1 if none.

cmlibs.utils.zinc.finiteelement.getMaximumNodeIdentifier(nodeset: Nodeset) → int

Returns:: Maximum node identifier in nodeset or -1 if none.

cmlibs.utils.zinc.finiteelement.getNodeNameCentres(nodeset: Nodeset, coordinates_field: Field, name_field: Field): Find mean locations of node coordinate with the same names. :param nodeset: Zinc Nodeset or NodesetGroup to search. :param coordinates_field: The coordinate field to evaluate. :param name_field: The name field to match. :return: Dict of names -> coordinates.

cmlibs.utils.zinc.finiteelement.get_element_node_identifiers(element: Element, eft: Elementfieldtemplate) → list

Get list of node identifiers used by eft in element in the order for eft.

Parameters:

element – The element to query.
eft – The element field template the nodes are mapped for.

Returns:

List of global node identifiers.

cmlibs.utils.zinc.finiteelement.get_element_node_identifiers_basis_order(element: Element, eft: Elementfieldtemplate) → list

Get list of node identifiers used by eft in element with the default number and order for the element basis. For example, with a bilinear lagrange basis, 4 node identifiers are always returned, possibly with repeats, even if the eft collapsed it to 3 nodes in an arbitrary order.

Parameters:

element – The element to query.
eft – The element field template the nodes are mapped for.

Returns:

List of global node identifiers.

cmlibs.utils.zinc.finiteelement.get_highest_dimension_mesh(fieldmodule: Fieldmodule): Get highest dimension non-empty mesh in Zinc fieldmodule. :return: Zinc Mesh or None if all are empty.

cmlibs.utils.zinc.finiteelement.get_identifiers(nodeset: Nodeset) → list

Create a list of all the identifiers used in the given nodeset.

Parameters:: nodeset – Nodeset to search for identifiers.
Returns:: A list of identifiers used by the given nodeset.

cmlibs.utils.zinc.finiteelement.get_maximum_element_identifier(mesh: Mesh) → int

Returns:: Maximum element identifier in mesh or -1 if none.

cmlibs.utils.zinc.finiteelement.get_maximum_node_identifier(nodeset: Nodeset) → int

Returns:: Maximum node identifier in nodeset or -1 if none.

cmlibs.utils.zinc.finiteelement.get_next_unused_node_identifier(nodeset: Nodeset, start_identifier=1) → int

Returns:: Unused node identifier >= start_identifier.

cmlibs.utils.zinc.finiteelement.get_node_name_centres(nodeset: Nodeset, coordinates_field: Field, name_field: Field): Find mean locations of node coordinate with the same names. :param nodeset: Zinc Nodeset or NodesetGroup to search. :param coordinates_field: The coordinate field to evaluate. :param name_field: The name field to match. :return: Dict of names -> coordinates.

cmlibs.utils.zinc.finiteelement.interpolate_cubic_hermite_derivative(v1, d1, v2, d2, xi): Get derivatives of cubic Hermite interpolated from v1, d1 to v2, d2. :param v1: and :param v2: Values at xi = 0.0 and xi = 1.0, respectively. :param d1: and :param d2: Derivatives w.r.t. xi at xi = 0.0 and xi = 1.0, respectively. :param xi: Position in curve, nominally in [0.0, 1.0]. :return: List of interpolated derivatives at xi.

cmlibs.utils.zinc.finiteelement.is_field_defined_for_nodeset(field, nodeset=None, nodeset_domain=None)

Determine if the given field is defined for any member of the given nodeset, return True if the field is defined on at least one member and False otherwise. If neither nodeset nor nodeset_domain is specified then False is returned. If nodeset is given and nodeset_domain is also passed then the nodeset_domain will be ignored.

Parameters:

field – Field to use for determining if defined any member in the given nodeset.
nodeset – Nodeset to determine if field is defined on any member.
nodeset_domain – Nodeset domain to determine if field is defined on any member.

Returns:

True if the field is defined on at least one member, False otherwise.

cmlibs.utils.zinc.finiteelement.transformCoordinates(field: Field, rotation_scale, offset, time=0.0) → bool: Transform finite element field coordinates by matrix and offset, handling nodal derivatives and versions. Limited to nodal parameters, rectangular cartesian coordinates :param field: the coordinate field to transform :param rotation_scale: square transformation matrix 2-D array with as many rows and columns as field components. :param offset: coordinates offset. :param time: time value. :return: True on success, otherwise false.

cmlibs.utils.zinc.finiteelement.transform_coordinates(field: Field, rotation_scale, offset, time=0.0) → bool: Transform finite element field coordinates by matrix and offset, handling nodal derivatives and versions. Limited to nodal parameters, rectangular cartesian coordinates :param field: the coordinate field to transform :param rotation_scale: square transformation matrix 2-D array with as many rows and columns as field components. :param offset: coordinates offset. :param time: time value. :return: True on success, otherwise false.

General

General utilities for working with the Zinc library.

class cmlibs.utils.zinc.general.AbstractNodeDataObject(field_names, time_sequence=None, time_sequence_field_names=None): A node data object for managing node fields. Offers ability to work with a time sequence and fields that make use of time sequences.

class cmlibs.utils.zinc.general.ChangeManager(change_object)

Python Context Manager minimising change messages for a Zinc object, for use whenever making multiple changes to the object or objects it owns. Ensures beginChange, endChange are always called, even with exceptions. Usage:

with ChangeManager(object):
    # make multiple changes to object or objects it owns

class cmlibs.utils.zinc.general.HierarchicalChangeManager(change_object)

Python Context Manager minimising change messages for a Zinc object, for use whenever making multiple changes to the object or objects it owns. Hierarchical version for use with Region object. Ensures beginHierarchicalChange, endHierarchicalChange are always called, even with exceptions. Usage:

with HierarchicalChangeManager(region):
    # make multiple changes to object or objects it owns including fieldmodules and childregions

cmlibs.utils.zinc.general.createNode(field_module, data_object, identifier=-1, node_set_name='nodes', time=None)

Create a Node in the field_module using the data_object. The data object must supply a ‘get_field_names’ method and a ‘get_time_sequence’ method. Derive a node data object from the ‘AbstractNodeDataObject’ class to ensure that the data object class meets it’s requirements.

Optionally use the identifier to set the identifier of the Node created, the time parameter to set the time value in the cache, or the node_set_name to specify which node set to use the default node set is ‘nodes’.

Parameters:

field_module – The field module that has at least the fields defined with names in field_names.
data_object – The object that can supply the values for the field_names through the same named method.
identifier – Identifier to assign to the node. Default value is ‘-1’.
node_set_name – Name of the node set to create the node in.
time – The time to set for the node, defaults to None for nodes that are not time aware.

Returns:

The node identifier assigned to the created node.

cmlibs.utils.zinc.general.create_node(field_module, data_object, identifier=-1, node_set_name='nodes', time=None)

Create a Node in the field_module using the data_object. The data object must supply a ‘get_field_names’ method and a ‘get_time_sequence’ method. Derive a node data object from the ‘AbstractNodeDataObject’ class to ensure that the data object class meets it’s requirements.

Optionally use the identifier to set the identifier of the Node created, the time parameter to set the time value in the cache, or the node_set_name to specify which node set to use the default node set is ‘nodes’.

Parameters:

field_module – The field module that has at least the fields defined with names in field_names.
data_object – The object that can supply the values for the field_names through the same named method.
identifier – Identifier to assign to the node. Default value is ‘-1’.
node_set_name – Name of the node set to create the node in.
time – The time to set for the node, defaults to None for nodes that are not time aware.

Returns:

The node identifier assigned to the created node.

cmlibs.utils.zinc.general.defineStandardGraphicsObjects(context: Context)

Defines Zinc standard objects for use in graphics, including a number of graphical materials and glyphs.

Parameters:: context – A Zinc context

cmlibs.utils.zinc.general.define_standard_graphics_objects(context: Context)

Defines Zinc standard objects for use in graphics, including a number of graphical materials and glyphs.

Parameters:: context – A Zinc context

Material

Utilities for working with Zinc graphics materials.

cmlibs.utils.zinc.material.createMaterialUsingImageField(region: Region, image_field: Field, colour_mapping_type=None, image_range=None) → Material

Use an image field in a material to create an OpenGL texture. Returns the created material.

Parameters:

region – Used to obtain materialmodule, spectrummodule.
image_field – Zinc FieldImage.
colour_mapping_type – Zinc Spectrumcomponent colour mapping type or None for default rainbow.
image_range – Sequence of minimum, maximum, or None to use default.

Returns:

The material that contains the image field as a texture.

cmlibs.utils.zinc.material.create_material_using_image_field(region: Region, image_field: Field, colour_mapping_type=None, image_range=None) → Material

Use an image field in a material to create an OpenGL texture. Returns the created material.

Parameters:

region – Used to obtain materialmodule, spectrummodule.
image_field – Zinc FieldImage.
colour_mapping_type – Zinc Spectrumcomponent colour mapping type or None for default rainbow.
image_range – Sequence of minimum, maximum, or None to use default.

Returns:

The material that contains the image field as a texture.

Image Module

cmlibs.utils.image.extractImageCorners(directory, filename)

Extract the image corners from an image that is assumed to be a DICOM image. Corners are returned as:

[bottom left (bl), bottom right (br), top left (tl), top right (tr)]

Parameters:

directory – the directory where the file given with filename exists.
filename – the filename of the file to interrogate.

Returns:

the corners of the image [bl, br, tl, tr]