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>)

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 (func) – Function to call with status messages. If given, this function is called with a string describing the status. If set to None, no status updates are issued.

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.