CAD Models

For use with ray casting or rendering images, it is common to need to make use of scene CAD models when using the calcam API. This is done with the calcam.CADModel class, documented below. For examples of usage, see the Examples page.

class calcam.CADModel(model_name=None, model_variant=None, status_callback=<function print_status>, verbose=True)

Class for representing a CAD model in Calcam.

Parameters:

  • model_name (str) – Either the machine name of a CAD model in Calcam’s model search path, or filename of a .ccm file to load the model from.

  • model_variant (str) – Name of the model variant to load. If not specified, the default variant specified in the CAD model is loaded.

  • status_callback (callable) – Function to call with status messages. If given, this function will be called with a string describing what this class is currently doing (e.g. loading files etc) or None which signifies clearing the previous status. This is mainly used for integration with the Calcam GUI.

  • verbose (bool) – Whether to issue status updates to status_callback (default) or be completely silent if set to False.

enable_only(features)

Disable all model parts except those specified.

Parameters:

features (str or list of str) – Name(s) of the feature(s) and/or group(s) to have enabled.

format_coord(coords)

Return a pretty string giving information about a specified 3D position.

Parameters:

coords (array-like) – 3 element array-like specifying a point in 3D as X,Y,Z in metres.

Returns:

String containing information about the given point.

Return type:

str

get_colour(features=None)

Get the current colour of part or all of the CAD model.

Parameters:

features (list of str) – List of names of the features to get the colour for. If not specified, all feature colours are returned.

Returns:

List of 3 element tuples specifying the colours (R,G,B) of the given features, where R, G and B range from 0 to 1.

Return type:

List

get_enabled_features()

Get a list of the currently enabled features.

Returns:

Names of the currently enabled features.

Return type:

list of str

get_extent()

Get the extent of the model in 3D space.

Returns:

6 element array specifying the extent of the model in metres: [x_min, x_max, y_min, y_max, z_min, z_max]

Return type:

np.array

get_feature_list()

Get a list of the names of all features which constitute the model.

Returns:

List of feature names.

Return type:

list of str

get_group_enable_state(group=None)

Check the enable status of a named group of features.

Parameters:

group (str) – Name of the group to check. If not given, the entire model is taken to be the group.

Returns:

0 if no features in the group are anebled; 1 if some features in the group are enabled; 2 if all features in the group are enabled.

Return type:

int

get_linewidth(features=None)

Get the line width used for rendering the model as wireframe.

Parameters:

features (list of str) – List of names of the features to get the line width for. If not specified, all feature line widths are returned.

Returns:

List of the line widths.

Return type:

list of float

get_status_callback()

Get the current callback function

Returns:

Current status callback function, if present.

Return type:

func or NoneType

intersect_with_line(line_start, line_end, surface_normal=False)

Find the first intersection of a straight line segment with the CAD geometry, if one occurs (“first” meaning first when moving from the start to the end of the line segment). Optionally also calculates the surface normal vector of the CAD model at the intersection point.

Parameters:

  • line_start (sequence) – 3-element sequence x,y,z of the line segment start coordinates (in metres)

  • line_end (sequence) – 3-element sequence x,y,z of the line segment end coordinates (in metres)

  • surface_normal (bool) – Whether or not to calculate the surface normal vector of the CAD model at the intersection.

Returns:

  • bool : Whether or not the line segment intersects the CAD geometry

  • np.array : 3-element NumPy array with x,y,z position of the intersection. If there is no intersection, line_end is returned.

  • np.array or None : Only returned if surface_normal = True; the surface normal at the intersection. If there is no intersection, returns None.

Return type:

Multiple return values

reset_colour(features=None)

Reset the colour of part or all of the CAD model to the default(s).

Parameters:

features (list of str) – List of features for which to reset the colours. If not given, all features will have their colours reset.

set_colour(colour, features=None)

Set the colour of part or all of the CAD model.

Parameters:

  • colour (tuple) – 3-element tuple specifying a colour in (R,G,B) where the values are in the range 0 to 1.

  • features (list of str) – List of names of the features to set this colour. If not specified, applies to the whole model.

set_features_enabled(enable, features=None)

Enable or disable parts of the CAD model.

Parameters:

  • enable (bool) – Whether to set the relevant features as enabeled (True) or disabled (False).

  • features (str or list of str) – Name(s) of the feature(s) and/or group(s) of features of to enable or disable. If not specified, applies to all features in the model.

set_flat_shading(flat_shading)

Set flat shading (no lighting applied to model rendering) enabled or disabled.

Parameters:

flat_shading (bool) – Whether to enable or disable flat shading.

set_linewidth(linewidth, features=None)

Set the line width used when rendering the CAD model as wireframe.

Parameters:

  • linewidth (float) – Line width.

  • features (list of str) – List of names of the features to set the line width for. If not specified, applies to the whole model.

set_status_callback(status_callback)

Set the status callback function.

The given function will be called with a string when the CAD model object does something, and is called with None when the operatio is finished. If set to None, the object will provide no output when it is busy doing things.

Parameters:

status_callback (fun) – Status callback function.

set_wireframe(wireframe)

Enable or disable rendering the model as wireframe.

Parameters:

wireframe (bool) – Whether to render as wireframe.

unload()

Unloads the CAD model object.