cee::ug::UnstructGridModel

class UnstructGridModel : public Model

UnstructGridModel is a subclass of Model

which adds specific model

structure and functionality for representing scientific and engineering models, e.g.

finite element data.

It contains a description of visual presentation and feature extraction management such as part settings, result settings (scalar, vector and displacement), isosurfaces, isovolumes, cutting planes, particle traces and mirror settings.

The geometry data model consists of nodes, elements, element connectivity, and aggregations to parts. Nodes and elements can be index- or id-based. Elements also have optional user properties. Parts binds elements and nodes. A geometry consists of a collection of parts. The unstructured grid component supports multiple geometries per state and allows combination of static and dynamic geometries.

Supported element types are point, beam, triangle, quad, tetrahedron, pyramid, pentahedron, hexahedron and polyhedron. See Element::Type for full list of element types.

A View has a collection of models. Add a model to the view with View::addModel(). See View for more information.

../_images/uml_unstruct.png

Data source

The model object owns a data source containing the actual data repository (nodes, topography and result data). Data sources can be file based or build by programmatic input. See DataSource for more information.

Set the data source by setDataSource() and get the current data source using dataSource().

Model specification

The model specification describes the visual content of the model. For instance, loaded states, which scalar result to show as fringes or perhaps vector result. Each model owns a ModelSpec object which can be accessed through modelSpec().

When an attribute in the model specification has been set or altered, updateVisualization() must be called to apply the changes to the visualized model.

Example - Set a scalar result to be visualized as fringes:

// Sets a fringes result in the model specification.
int scalarResultId = 1;
ugModel->modelSpec().setFringesResultId(scalarResultId);

//Toggle on fringes visibility for the parts to see the visualized fringes.
ugModel->partSettings(geometryIndex, partId)->setFringesVisible(true);

// Since a setting in the model specification has been altered, the visualization needs to be updated for 
the change to take effect.ugModel->updateVisualization();

Settings

  • Part settings

    Part settings contains various attributes for a part. Part settings can, for instance, be visibility, draw style, transparency, color, result visibility. Get the part settings for a given part by calling partSettings() with the requested geometry index and part id.

    A quick way to alter settings for all parts is using the part iterator.

cee::ug::PartSettingsIterator it(ugModel.get());
while (it.hasNext())
{
    cee::ug::PartSettings* partSettings = it.next();
    partSettings->setFringesVisible(true);
}

  • Scalar settings Scalar settings contains settings for a scalar result. Scalar settings can, for instance, be range, number of levels, legend visibility, color scheme and filtering. Get the scalar setting for a given scalar result by calling scalarSettings() with the requested scalar result id.

  • Vector settings

    Vector settings contains settings for a vector result. Vector settings can, for instance, be scaling and color mode. Get the vector settings for a given vector result by calling vectorSettings() with the requested vector id.

  • Displacement setting

    Displacement settings contains settings for a displacement result. Displacement settings are relative and absolute scaling values. Get the displacement settings for a given displacement result by calling displacementSettings() with the requested displacement id.

  • Mirror settings

    Mirror settings contains setting for the mirror functionality. Mirror settings can, for instance, be enabled true/false, number of passes and Plane information. Get the mirror settings with mirrorSettings().

  • Model settings

    Model settings contains miscellaneous setting for the unstructured grid model. For instance, mesh color, highlight color, undeformed model color/draw style, shader settings and UnstructGridModel related font selection. Get the model settings with modelSettings().

Feature extraction

  • Cutting planes

    Cutting planes are slices through the model onto which any scalar or vector fields can be mapped. A cutting plane is defined by a position and a normal vector. Both position and normal can be changed interactively.

    Any number of cutting planes can be defined and displayed, and various display attributes can be set separately for each one.

    Add a cutting plane with addCuttingPlane(). Remove a specified cutting plane with removeCuttingPlane() or remove all cutting planes with removeAllCuttingPlanes(). Get number of cutting planes in the model with cuttingPlaneCount() and access an existing cutting plane using cuttingPlane() with the requested cutting plane index.

cee::PtrRef<cee::ug::CuttingPlane> cuttingPlane = new cee::ug::CuttingPlane();
ugModel->addCuttingPlane(cuttingPlane.get());

  • Isosurface

    Isosurfaces may be derived based on any scalar variable in a scalar result. In addition, a second scalar result can be mapped onto the surface, showing for instance the variation of temperature over a surface of Constant pressure. Any number of isosurfaces can be defined and displayed, and various display attributes can be set separately for each one. Add an isosurface with addIsosurface(). Remove a specified isosurface with removeIsosurface() or remove all isosurfaces with removeAllIsosurfaces(). Get number of isosurfaces in the model with isosurfaceCount() and access an existing isosurface using isosurface() with the requested isosurface index.

cee::PtrRef<cee::ug::Isosurface> isoSurface = new cee::ug::Isosurface();
ugModel->addIsosurface(isoSurface.get());

  • Isovolume

    Isovolumes may be derived based on any scalar variable in a scalar result. In addition, a second scalar result can be mapped onto the surface, showing for instance the variation of temperature over a volume computed from Pressure. Any number of isovolumes can be defined and displayed, and various display attributes can be set separately for each one. Add an isovolume with addIsovolume(). Remove a specified isovolume with removeIsovolume() or remove all isovolumes with removeAllIsovolumes(). Get number of isovolumes in the model with isovolumeCount() and access an existing isovolume using isovolume() with the requested isovolume index.

cee::PtrRef<cee::ug::Isovolume> isoVolume = new cee::ug::Isovolume();
ugModel->addIsovolume(isoVolume.get());

  • Particle traces

    To visualize features of a vector field, it is possible to define streamlines; the paths of mass less particles through the flow. A particle trace group is defined by seed points and a vector result. The particle trace can be animated. Add a particle trace group can be set with addParticleTraceGroup(). Remove the particle trace group with removeParticleTraceGroup().

The model controls which frame is current. Get number of frames in the model with frameCount(). Set and get current frame with setCurrentFrameIndex() and currentFrameIndex().

Find an intersection point with rayIntersect() or rayIntersectAllHits(). It takes a Ray object from the View and creates one or more HitItem object describing where the ray hit the model. See HitItem for a listing of available hit information. Other ray intersection functions are regionIntersect() and polygonIntersect().

Example

Example on creating a model with a memory data source and custom built geometry.

Creates a model and a memory data source. The constructor of the data source takes a unique id and the number of geometries (here 1). Set the data source in the created model.

cee::PtrRef<cee::ug::UnstructGridModel> ugModel = new cee::ug::UnstructGridModel();
cee::PtrRef<cee::ug::DataSourceMemory> dataSource = new cee::ug::DataSourceMemory(1, 1);
ugModel->setDataSource(dataSource.get());

Creates the state. Set number of geometries to 1 in the constructor.

int stateId = 1;
cee::PtrRef<cee::ug::DataState> state = new cee::ug::DataState(stateId, 1);
dataSource->addState(state.get());

Sets the newly created state to current in the model specification.

ugModel->modelSpec().setStateId(stateId);

Creates the geometry and add it to the state at index 0.

int geometryIndex = 0;
cee::PtrRef<cee::ug::DataGeometry> geo = new cee::ug::DataGeometry();
state->setGeometry(geometryIndex, geo.get());

Build a geometry containing the necessary parts, nodes and elements. Optionally, add results.

When finished, update the metadata in the data source directory with all new content.

// Set the part info
cee::ug::PartInfo partInfo(partId, "My part");
dataSource->directory()->setPartInfo(geometryIndex, partInfo);
// Set the state info
cee::ug::StateInfo stateInfo(stateId, "My state", 0.0);
dataSource->directory()->setStateInfo(stateInfo);

Add the finished model to the view.

cee::vis::View* view = getTutorialView();
View->addModel(ugModel.get());

See the complete source code at: UnstructGrid: Simple Model with Two Triangles

Public Types

enum UpdateAction

Update action. Used in updateVisualization() to specify level of update needed in order to optimize the update.

Values:

enumerator NORMAL

Default update. Settings and data are inspected and any needed update is performed.

enumerator HIGHLIGHT

Use this if you only used the setHighlight() method on Parts, CuttingPlane, Isosurface or Isovolume.

enumerator VISIBILITY

Use this if you only used the setVisible() method on Parts, CuttingPlane, Isosurface or Isovolume.

enumerator COLOR_AND_OPACITY

Use this if you only used the set*Color() or setOpacity() on Parts, CuttingPlane, Isosurface or Isovolume.

enumerator SCALAR_SETTINGS

Use this if you only used the ScalarSettings and ColorMapper methods.

enumerator COLOR_LEGEND

Visual configuration of the color legend (visible, text color, etc)

enumerator NODE_POSITIONS

Only the positions of the nodes have changed. Note: Only use this when the position of the nodes have changed, but not the number of nodes or element topology.

enumerator TRANSFORMATION_RESULTS

Only the transformation results have changed, if any.

enumerator CUTTING_PLANE

Use this if you only changed cutting plane parameters (apart from mapped result).

This will recompute the cutting plane in the current frame. All other frames will be computed whenever set visible using the setCurrentFrameIndex() method.

enumerator ISOSURFACE

Use this if you only changed isosurface parameters (apart from mapped result).

This will recompute the isosurface in the current frame. All other frames will be computed whenever set visible using the setCurrentFrameIndex() method.

enumerator ISOVOLUME

Use this if you only changed isovolume parameters (apart from mapped result).

This will recompute the isovolume in the current frame. All other frames will be computed whenever set visible using the setCurrentFrameIndex() method.

enumerator PARTICLE_TRACE

Use this if you only changed particle trace parameters (apart from mapped result).

This will recompute the particle trace in the current frame. All other frames will be computed whenever set visible using the setCurrentFrameIndex() method.

enumerator REGENERATE_ALL

Force recreation of the supporting display model.

Also forces reading of data from an interface (if in use).

Public Functions

UnstructGridModel()

Constructs an empty model.

const DataSource *dataSource() const

Returns the data source.

DataSource *dataSource()

Returns the data source.

void setDataSource(DataSource *dataSource)

Sets the data source.

Warning

The added object is reference counted and should never be created on the stack or deleted!

const ModelSpec &modelSpec() const

Gets the model specification.

ModelSpec &modelSpec()

Gets the model specification.

virtual bool updateVisualization(UpdateAction updateAction = NORMAL, Progress *progress = NULL, Error *error = NULL)

Updates the visualization based on the current settings.

This method needs to be called whenever a change is made to the settings or data in the model.

To optimize the update, an UpdateAction can be provided to limit the update to a specific task. Note that calling updateVisualization(UnstructGridModel::NORMAL) will always work, and the other flags are just for optimization.

A normal use case for the UpdateAction is frequent operations that should be as fast as possible. E.g. the user hides or shows a part, a user selects an object (part, cutting plane, isosurface, isovolume) either with highlight (halo) (using the HIGHLIGHT UpdateAction) or with changing the color or opacity (using the COLOR_AND_OPACITY UpdateAction) action.

Another use case is for sliders on scalar ranges, where the update of the model can be very fast if only the SCALAR_SETTINGS UpdateAction is used.

If you do operations that involve multiple UpdateActions, just call updateVisualization(UnstructGridModel::NORMAL)

You should try to avoid unnecessary calls to updateVisualization() as it will take some time even if there are no changes. Try to structure the code and only call this once if you change several settings.

Note! All views containing the model needs to be repainted/invalidated after calling this method to show the result of the update.

See also

UpdateAction

void clearVisualization()

Clears visualization.

virtual size_t startUpdateVisualizationPerFrame(Error *error = NULL)

Prepares for a per-frame update of the visualization.

Returns the number of frames to generate.

This is useful when setting up animations that will take some time, as the animation frames can be rendered as soon as they are finished, thus giving the user feedback and “hiding” a a lot of the setup time.

To do a per-frame animation setup, first configure the model spec as you would do with updateVisualization(). Then you call this method which prepares the per frame update and returns the number of frames to generate. Then you loop over all these frames and call the updateVisualizationForFrame() method.

Example:

size_t numFrames = unstructModel->startUpdateVisualizationPerFrame();
for (size_t i = 0; i < numFrames; ++i)
{
    unstructModel->updateVisualizationForFrame(i);

    // An immediate redraw is required, as the normal requestRedraw() will queue the message and not repaint
    // until the loop is done. 
    view->requestImmediateRedraw();
}

Just to clarify, these two pieces of code gives the same result:

unstructModel->updateVisualization();

and

size_t numFrames = unstructModel->startUpdateVisualizationPerFrame();
for (size_t i = 0; i < numFrames; ++i)
{
    unstructModel->updateVisualizationForFrame(i);
}

virtual bool updateVisualizationForFrame(size_t frameIndex, Error *error = NULL)

Updates the visualization for the given frame.

Note! startUpdateVisualizationPerFrame() must be called prior to this method.

See startUpdateVisualizationPerFrame() for more information on how to do per-frame update of the visualization.

const ModelSettings &modelSettings() const

Returns a reference to the model settings for this model.

ModelSettings &modelSettings()

Returns a reference to the model settings for this model.

bool rayIntersect(int x, int y, const vis::View &view, HitItem *hitItem) const

Does picking at the given screen coordinates, returning true if anything was hit.

The x and y coordinates must be specified in OpenGL style coordinates, which means a right handed coordinate system with the origin in the lower left corner of the window.

The hit item object describes where the ray created from the screen coordinates hit the model. See HitItem for a listing of available hit information.

Returns true if something was hit.

See also

Ray and cee::ug::HitItem

bool rayIntersectAllHits(int x, int y, const vis::View &view, HitItemCollection *hitItems) const

Does picking at the given screen coordinates, returning true if anything was hit and returning all overlapping items if any.

The x and y coordinates must be specified in OpenGL style coordinates, which means a right handed coordinate system with the origin in the lower left corner of the window.

The hit item objects describe where the ray created from the screen coordinates hit the model. See HitItem for a listing of available hit information.

Returns true if something was hit.

See also

Ray and cee::ug::HitItem

bool regionIntersect(int x, int y, unsigned int width, unsigned int height, const vis::View &view, bool acceptPartiallyContainedItems, bool includeElementIndices, std::vector<PartHitItems> *itemList) const

Finds the parts (and optionally elements) that are (partially) inside the given region.

The partHitItemsList will contain all parts that are inside the given region. If acceptPartiallyContainedParts is set to true, parts will be considered inside if they are partially inside (at least one pixel of one item) the region. If false, the entire part needs to be completely inside the region.

If includeElementIndices is specified, each PartHitItems will also have a list of the elements that are (partially) within the given region. If only the parts are needed, it is faster to set this to false for the method to only consider the part and not each element.

The x and y coordinates must be specified in OpenGL style coordinates, which means a right handed coordinate system with the origin in the lower left corner of the window. The width and height is in pixels.

Returns true if any parts was accepted (partHitItemsList.size() > 0)

bool polygonIntersect(const std::vector<Vec2f> &polygonInWindowCoordinates, const vis::View &view, bool acceptPartiallyContainedItems, bool includeElementIndices, std::vector<PartHitItems> *itemList) const

Finds the parts (and optionally elements) that are (partially) inside the given polygon defined in window coordinates.

The polygon is described by polygonInWindowCoordinates which contains the points defining the polygon outer contour. The array should contain all nodes in the polygon in the right order. Polygon edges will be created between 0 -> 1, 1 -> 2, …. n -> 0, so there is no need to repeat the first node in order to close the polygon.

The coordinates defining the polygon must be specified in OpenGL style coordinates, which means a right handed coordinate system with the origin in the lower left corner of the window.

Example: (100,100), (200, 100), (200, 200), (200, 100) This defines a square with lower left corner of (100, 100) and sides 100 long.

The partHitItemsList will contain all parts that are inside the given polygon. If acceptPartiallyContainedParts is set to true, parts will be considered inside if they are partially inside (at least one pixel of one item) the polygon. If false, the entire part needs to be completely inside the region.

If includeElementIndices is specified, each PartHitItems will also have a list of the elements that are (partially) within the given polygon. If only the parts are needed, it is faster to set this to false for the method to only consider the part and not each element.

Returns true if any parts was accepted (partHitItemsList.size() > 0)

bool rayIntersect(const Ray &ray, HitItem *hitItem) const

Takes a Ray object and returns a HitItem object.

The HitItem object describes where the ray hit the model. See HitItem for a listing of available hit information.

Returns true if something was hit.

See also

Ray and HitItem

bool rayIntersectAllHits(const Ray &ray, HitItemCollection *hitItems) const

Takes a Ray object and returns all HitItems objects hit by it.

A HitItem object describes where the ray hit the model. See HitItem for a listing of available hit information.

Returns true if something was hit.

See also

Ray and HitItem

size_t frameCount() const

Returns the number of frames currently available.

size_t currentFrameIndex() const

Returns the index of the current frame.

Returns UNDEFINED_SIZE_T if no frames are present.

int currentStateId() const

Returns the id of the current DataState (the data state in the current frame).

Returns -1 if no current data state.

void setCurrentFrameIndex(size_t frameIndex)

Sets the current frame (the frame to render).

frameIndex must be [0 .. numFrames() - 1]

double particleTraceTime() const

Returns the current particle trace time.

Undefined double indicates the entire trace is shown

void setParticleTraceTime(double time)

Sets the current particle trace time.

Set to undefined double for show entire trace.

virtual BoundingBox boundingBox()

Returns the bounding box of the model.

The bounding box will include all frames if an animation is present

virtual BoundingBox frameBoundingBox(size_t frameIndex)

Returns the bounding box of the model in the given frame.

virtual BoundingBox partBoundingBox(size_t frameIndex, size_t globalGeometryIndex, int partId)

Returns the bounding box of the part in the given frame.

virtual Str modelInfo() const

Returns info regarding the current model contents.

PartSettings *partSettings(size_t globalGeometryIndex, int partId)

Returns the part settings for the part with partId.

Will create a settings object if no settings exists yet. This allows usage of this function before the visualization has been updated.

Returns

Returns pointer to modifiable settings object. Returns NULL if the specified partId is not present in the data source’s directory.

const PartSettings *existingPartSettings(size_t globalGeometryIndex, int partId) const

Returns the part settings for the part with partId.

Returns

Returns const pointer to settings object. Returns NULL if no settings exist.

ScalarSettings *scalarSettings(int resultId)

Returns scalar settings for the scalar result with resultId.

Will create a settings object if no settings exists yet. This allows usage of this function before the visualization has been updated.

Returns

Returns pointer to modifiable settings object. Returns NULL if the specified resultId is not present in the data source’s directory.

const ScalarSettings *existingScalarSettings(int resultId) const

Returns scalar settings for the scalar result with resultId.

Returns

Returns const pointer to settings object. Returns NULL if no settings exist.

VectorSettings *vectorSettings(int resultId)

Returns the vector settings for the vector result with resultId.

Will create a settings object if no settings exists yet. This allows usage of this function before the visualization has been updated.

Returns

Returns pointer to modifiable settings object. Returns NULL if the specified resultId is not present in the data source’s directory.

const VectorSettings *existingVectorSettings(int resultId) const

Returns vector settings for the vector result with resultId.

Returns

Returns const pointer to settings object. Returns NULL if no settings exist.

DisplacementSettings *displacementSettings(int resultId)

Returns the displacement settings for the displacement result with resultId.

Will create a settings object if no settings exists yet. This allows usage of this function before the visualization has been updated.

Returns

Returns pointer to modifiable settings object. Returns NULL if the specified resultId is not present in the data source’s directory.

const DisplacementSettings *existingDisplacementSettings(int resultId) const

Returns displacement settings for the result with resultId.

Returns

Returns const pointer to settings object. Returns NULL if no settings exist.

size_t cuttingPlaneCount() const

Returns number of of cutting planes.

const CuttingPlane *cuttingPlane(size_t index) const

Returns the cutting plane at the given index.

CuttingPlane *cuttingPlane(size_t index)

Returns the cutting plane at the given index.

void addCuttingPlane(CuttingPlane *cuttingplane)

Adds a cutting plane to the model.

Cutting planes cannot be shared between models. If you want to have the same cutting plane in two models, duplicate the plane. If you want to move a cutting plane, first remove it from the the original model before adding it to the second one.

Warning

The added object is reference counted and should never be created on the stack or deleted!

void removeCuttingPlane(const CuttingPlane *cuttingplane)

Removes the cutting plane cuttingplane from the model.

void removeAllCuttingPlanes()

Removes all cutting planes from the model.

size_t isosurfaceCount() const

Returns number of isosurfaces.

const Isosurface *isosurface(size_t index) const

Returns the isosurface at the given index.

Isosurface *isosurface(size_t index)

Returns the isosurface at the given index.

void addIsosurface(Isosurface *isosurf)

Adds an isosurface to the model.

Isosurfaces cannot be shared between models. If you want to have the same isosurface in two models, duplicate the surface. If you want to move an isosurface from one model to another, remove it first from the original model before adding it to the second one.

Warning

The added object is reference counted and should never be created on the stack or deleted!

void removeIsosurface(const Isosurface *isosurf)

Removes the isosurface isosurf from the model.

void removeAllIsosurfaces()

Removes all isosurfaces from the model.

size_t isovolumeCount() const

Returns number of isovolumes.

const Isovolume *isovolume(size_t index) const

Returns the isovolume at the given index.

Isovolume *isovolume(size_t index)

Returns the isovolume at the given index.

void addIsovolume(Isovolume *isosurf)

Adds an isovolume to the model.

Isovolumes cannot be shared between models. If you want to have the same isovolume in two models, duplicate the volume. If you want to move an isovolume from one model to another, remove it first from the original model before adding it to the second one.

Warning

The added object is reference counted and should never be created on the stack or deleted!

void removeIsovolume(const Isovolume *volume)

Removes the isovolume volume from the model.

void removeAllIsovolumes()

Removes all isovolumes from the model.

size_t particleTraceGroupCount() const

Returns the number of particle trace groups in the model.

const ParticleTraceGroup *particleTraceGroup(size_t index) const

Returns the particle trace group at the given index.

ParticleTraceGroup *particleTraceGroup(size_t index)

Returns the particle trace group at the given index.

void addParticleTraceGroup(ParticleTraceGroup *group)

Adds a new particle trace group to the model.

Particle trace groups cannot be shared between models. If you want to have the same particle trace group in two models, duplicate the volume. If you want to move a particle trace group from one model to another, remove it first from the original model before adding it to the second one.

void removeParticleTraceGroup(const ParticleTraceGroup *group)

Removes the given particle trace group from the model.

void removeAllParticleTraceGroups()

Removes all particle trace groups from the model.

bool particleTraceTimeRange(size_t frameIndex, double *minimumTime, double *maximumTime) const

Gets the time range (min to max) of the given frame.

A valid frame index must be specified. Returns true if range is valid.

bool scalarRange(int resultId, double *min, double *max) const

Queries the model for the minimum and maximum of the specified scalar result.

The min/ returned is the minimum and maximum of the currently loaded time steps, and is not necessarily the global minimum and maximum.

Note! The queried result MUST exist in the current data model. To get the minimum and maximum of a result does not yet exist in the data model, load the result manually, call cee::ug::DataSourceInterface::loadState().

Returns true if result values were found.

bool vectorRange(int resultId, double *min, double *max) const

Queries the model for the min and max of the specified vector result.

The min/max returned is the minimum and maximum of the currently loaded time steps, and is not necessarily the global minimum and maximum.

Note! The queried result MUST exist in the current data model. To get the minimum and maximum of a result does not yet exist in the data model, load the result manually, call cee::ug::DataSourceInterface::loadState().

Returns true if result values were found.

bool displacementRange(double *min, double *max) const

Queries the model for the min and max of the current displacement result.

The min/max returned is the minimum and maximum of the currently loaded time steps, and is not necessarily the global minimum and maximum.

Note! The queried result MUST exist in the current data model. To get the minimum and maximum of a result does not yet exist in the data model, load the result manually, call cee::ug::DataSourceInterface::loadState().

Returns true if result values were found.

cee::Color3f elementSetColor(int setId) const

Returns the element set color for the specified set id.

void setElementSetColor(int setId, const Color3f &color)

Sets the /a color for the set given by /a setId.

MirrorSettings &mirrorSettings()

Returns the mirror settings for the model.

const MirrorSettings &mirrorSettings() const

Returns the mirror settings for the model.