models: Displayed data

This is a test to see whether the other members go away…

models: Displayed data

class Model(name, session)

Bases: State, Drawing

A Model is a Drawing together with an id number that allows it to be referenced in a typed command.

Model subclasses can be saved in session files.

Parameters:

name (str) – The name of the model.

id

Model/submodel identification: e.g., 1.3.2 is (1, 3, 2). Set and unset by Models instance.

Type:

None or tuple of int

SESSION_ENDURING

If True, then model survives across sessions.

Type:

bool, class-level optional

SESSION_SAVE

If True, then model is saved in sessions.

Type:

bool, class-level optional

SESSION_WARN

If True and SESSION_SAVE is False then a warning is issued when a session is saved explaining that session save is not supported for this type of model.

Type:

bool, class-level optional

add(models)

Experimental API . Add child models to this model.

Return type:

None

all_models()

Experimental API . Return all models including self and children at all levels.

property atomspec

Return the atom specifier string for this structure.

child_models()

Experimental API . Return child models.

cpp_del_model()

Experimental API . Called by the C++ layer to request that the model be deleted

delete()

Supported API . Delete this model.

property deleted

Return whether this model has already been deleted.

Returns:

Returns boolean value. True if model has been deleted; False otherwise.

property display

first_intercept(mxyz1, mxyz2, exclude=None)

Experimental API . So that generic models can be properly picked. Most model classes override this.

get_selected(include_children=False, fully=False)

Experimental API . Is this model selected? If fully is true then are all parts of this model selected?

has_formatted_metadata(session)

Experimental API . Can override both this and ‘get_formatted_metadata’ if lazy evaluation desired

property id_string

Return the dot-separated identifier for this model. A top-level model (one that is not a child of another model) will have no dots in its identifier. A child model identifier consists of its parent model identifier, followed by a dot (period), followed by its (undotted) identifier within the parent model.

Returns:

A string. If the model has not been assigned an identifier, an empty string is returned.

interpolate_scene(scene1_data, scene2_data, fraction, *, switchover=False)

Experimental API . Restore model to state interpolated as a fraction between the two scene datas. For parts of the model that aren’t interpolable, change to the second state when ‘switchover’ is True. If no parts of the model are interpolable then you needn’t implement this method (restore_scene() is sufficient).

property name

property overall_color

Getting the overall color may give the dominant color. It also might return None (many colors but no dominant color) or False (model does not support [external] coloring, e.g. color key). Setting the overall color will set the model to that color. Color values are rgba uint8 arrays. The supported attribute name is ‘overall_color’. The ‘model_color’ attribute is deprecated and only retained for backwards compatibility.

property position

property positions

restore_geometry(session, data)

Experimental API . Restore model and drawing state saved with save_geometry().

restore_scene(scene_data)

Experimental API . Restore model to state from scene_data (obtained from take_snapshot() with State.SCENE flag)

classmethod restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

save_geometry(session, flags)

Experimental API . Return state for saving Model and Drawing geometry that can be restored with restore_geometry().

property selected

selected indicates if this model has any part selected but does not include children.

show_metadata(session, *, verbose=False, log=None, **kw)

Experimental API . called by ‘log metadata’ command.

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

class Models(session)

Bases: StateManager

Models manages the Model instances shown in the scene belonging to a session. It makes a root model (attribute scene_root_model) that the graphics View uses to render the scene.

Another major function of Models is to assign the id numbers to each Model. An id number is a non-empty tuple of positive integers. A Model can have child models (m.child_models()) and usually has a parent model (m.parent). The id number of a child is a tuple one longer than the parent and equals the parent id except for the last integer. For instance a model with id (2,5) could have a child model with id (2,5,1). Every model has a unique id number. The id of the scene_root_model is the empty tuple, and is not used in commands as it has no number representation.

While most models are children at some depth below the scene_root_model it is allowed to have other models with single integer id that have no parent. This is currently used for 2D labels which are overlay drawings and are not part of the 3D scene. These models are added using Models.add(models, root_model = True). Their id numbers can be used by commands.

Most Model instances are added to the scene with Models.add(). In some instances a Model might be created for doing a calculation and is never drawn, is never added to the scene, and is never assigned an id number, so cannot be referenced in user typed commands.

add(models, parent=None, minimum_id=1, root_model=False, _notify=True, _need_fire_id_trigger=None, _from_session=False)

Experimental API . Assigns id numbers to the specified models and their child models. An id number is a tuple of positive integers. Each model has exactly one parent (except the scene root model). The id number of a parent is id number number of a child with the last integer removed. So the parent of a model with id (2,1,5) would have id (2,1).

In the typical case the specified models have model.id = None and model.parent = None. If the parent option is not given, each of these models are given an unused top level id number (tuple containing 1 integer), and child models are also given id numbers to all depths. If the parent argument is specified then each model is made a child of that parent.

There are other unusual cases. A specified model that has not been added may have model.id not None. This is a request to use this id for the model. The model with the parent id must already have been added. If the parent option is given and does not have the parent id, it is an error.

Another unusual case is that a specified model has already been added. This is a request to add the model to the specified parent, changing its id as needed. All children to all depths will also be assigned new ids. If the parent option is not specified it is an error. If the specified parent is the model itself or one of its descendants it is an error.

The specified models cannot contain a model which is a descendant of another specified model. That is an error.

In all cases if the parent option is given it must be a model that has already been added.

After a model has been added, model.id should not be changed except by this routine, or Models.assign_id(), or Models.remove() which sets model.id = None.

The root_model option allows adding a Model that has no parent. It will not be added as a child of the scene_root_model. This is currently used for 2D labels which are not part of the 3D scene, but instead are overlays drawn on top of the graphics. A root model has an id that is unique among all model ids so it can be specified in user typed commands.

assign_id(model, id)

Experimental API . Parent model for new id must already exist.

close(models)

Experimental API . Remove the models from the scene as well as all child models to all depths, and delete the models. Models that are not part of the scene are deleted, and models that have already been deleted are ignored.

remove(models)

Experimental API . Remove the specified models from the scene as well as all their children to all depths. The models are not deleted. Their model id numbers are set to None and they are removed as children from parent models that are still in the scene.

reset_state(session)

Experimental API . Reset state to data-less state

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

class PickedModel(model, distance)

Bases: Pick

description()

Experimental API . Text description of the picked object.

select(mode='add')

Experimental API . Cause this picked object to be highlighted (‘add’ mode), unhighlighted (‘subtract’ mode) or toggle highlighted (‘toggle’ mode).

specifier()

Experimental API . Command specifier for the picked object.

class Surface(name, session)

Bases: Model

A surface is a type of model where vertex coloring, style (filled, mesh, dot) and masking can be controlled by user commands.

classmethod restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

ancestor_models(models)

Experimental API . Return set of ancestors of models that are not in specified models.