Structure Management

Intro

A structure is a geometric object visualized in Polyscope, like a mesh or a point cloud. The first step in seeing your data in Polyscope is to register one or more structures to add them to the visualization. Then, quantities can be added to these structures, like scalar functions, colors, or vector fields.

Each structure should be given a name which is unique among structures of that type. You can then use this name as a handle to perform operations on the structure; For instance, you can register a mesh with:

polyscope::registerSurfaceMesh("my mesh", vertices, faces);

Then, in a distant part of your code, add a scalar function to it with:

polyscope::getSurfaceMesh("my mesh")->addScalarQuantity("some values", values);

This avoids the need to pass a pointer to the structure you created around your entire codebase.

Memory management

As a general policy, Polyscope always manages its own memory, and will take care of deleting anything it allocated. Whenever a routine returns a pointer (like getStructure()), it is a non-owning pointer. You should never delete one of these pointers. To delete a structure and free memory, see the removeStructure() methods below.

Registering structures

Each structure offers a register___(name, ...) function (like registerPointCloud()) which accepts the name of the structure and the data necessary to construct it. These functions will return a Structure* pointer which may be used to add quantities to the structure. See the relevant sections for documentation on each of these register functions.

The general form for registering structures is below; it may be useful if you are implementing your own structures.

bool registerStructure(Structure* structure, bool replaceIfPresent = true)

Register a new structure with Polyscope. The structure must have a Structure::name which is unique amongst all registered structures of that type.

Polyscope takes ownership of the memory when the structure is registered, and will delete it when no longer needed.

Note: most users will create structures via the individual registerPointCloud() (etc) functions, rather than this general form.

Accessing structures

Polyscope offers two patterns for calling methods on a registered structure: you can either use the pointer returned after structure creation, or refer to the structure by name.

#include "polyscope/surface_mesh.h"

// register a structure
polyscope::SurfaceMesh* psMesh = 
    polyscope::registerSurfaceMesh("my mesh", vertices, faces);

// access with the pointer
psMesh->addScalarQuantity("some values", values);

// access by name
polyscope::getSurfaceMesh("my mesh")->addScalarQuantity("some values", values);

The former is concise and programmatic, while the latter avoids the need to keep track of a variable.

As before, each structure offers a get___(name) method, like getSurfaceMesh(name) which can be used to get a pointer to the structure of that type by name. The general form below may be useful if you are implementing your own structures.

Structure* getStructure(std::string type, std::string name = "")

Get a pointer to a registered structure. The type must be the unique string corresponding to the structure type.

As a convenience, if the name may be argument omitted only if there is exactly one structure of that type.

If not such structure is available, nullptr will be returned.

Note: most users will get structures via the individual getPointCloud() (etc) functions, rather than this general form.

Removing structures

If no longer needed, structures can be removed by name or by pointer. Removing a structure frees memory for the underlying objects, invalidating all references to the structure and its quantities.

void removeStructure(Structure* structure, bool errorIfAbsent = true)

Remove the specified structure and free objects associated with it.

If errorIfAbsent == true, and error will be thrown if there is no such structure registered, otherwise the function will return silently.

void removeStructure(std::string type, std::string name, bool errorIfAbsent = true)

Identical to removeStructure(Struture*), but accepts a type name and name instead.

void removeStructure(std::string name, bool errorIfAbsent = true)

Identical to removeStructure(Struture*), but accepts a name instead. Will fail unless there is exactly one structure with the given name across all structure types.

Structure options

These basic options are shared by all structures. Structure options are managed as persistent values, and thus will persist if a new structure is registered with the same name.

Enabled

If a structure is disabled, it will be hidden from view, along with any quantities associated with that structure.

bool Structure::isEnabled()

Is the structure enabled?

void Structure::setEnabled(bool newVal)

Set the structure to be enabled or disabled.

Transparency

Set the transparency parameter for the structure. 1 is fully opaque (the default), and 0 is fully transparent. When the first structure has transparency applied, transparent rendering will be automatically enabled.

Transparency can be controlled in the UI via the structure’s [Options] --> [Transparency] menu.

float Structure::getTransparency()

Get the transparency parameter for the structure.

void Structure::setTransparency(float alpha)

Set the transparancy for the structure.

Transforms

Each structure has an associated spatial transform applied to it for display in the scene. The transform encodes a translation, rotation, and scaling represented as a 4x4 homogeneous matrix. Initially this transformation is just the identity transform (it does nothing), but it can be adjusted to position the structures in your scene.

The transform can be controlled in the UI via the structure’s [Options] --> [Transform] menu.

void Structure::centerBoundingBox()

Set the transformation such that the structure’s bounding box is centered at the world origin.

void Structure::rescaleToUnit()

Set the transformation scaling such that the structure has length scale 1. This makes all structures roughly the same size.

void Structure::resetTransform()

Reset the structure’s transform to be the identity transform (i.e. to do nothing).

void Structure::setTransform(glm::mat4x4 transform)

Set a particular transform matrix.

void Structure::setPosition(glm::vec3 vec)

Set the transformation matrix such that structure is transformed to the position vec.

void Structure::translate(glm::vec3 vec)

Translate the transformation matrix by offset vec.

glm::mat4x4 Structure::getTransform()

Get the current transformation matrix.

glm::vec3 Structure::getPosition()

Get the translation component of the transformation matrix, the position to which the structure’s origin is translated.

Slice planes

Options relating to slice planes which may be present in the scene.

Slice plane options can be controlled in the UI via the structure’s [Options] --> [Slice Planes] menu.

Structure* Structure::setCullWholeElements(bool newVal)

If true, slice planes will affect this structure by culling whole elements (tets, triangles, points, etc), rather than slicing through the middle of the elements.

Note that not all structures may support culling whole elements. If not supported, this setting will do nothing.

Default: false.

bool Structure::getCullWholeElements()

Get whether the cull whole elements setting is applied.

Structure* Structure::setIgnoreSlicePlane(std::string name, bool newValue)

Set a slice plane to be ignored by the structure. If newValue is true the slice plane will be ignored, and if false it will be respected.

bool Structure::getIgnoreSlicePlane(std::string name)

Get if a slice plane is currently being ignored by the structure.