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);
polyscope::getSurfaceMesh("my mesh")->addScalarQuantity("some values", values);
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.
The following structures available in Polyscope. Many more structures are in developement!
- Surface Mesh
- Point Cloud
- Curve Network
- in progress: Camera View
- in progress: Curve
- in progress: Tet Mesh
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.
By default, these functions will error-out if a structure with that name is already in use. However, they take an optional boolean argument
allowReplacement argument, which can be set to
true to replace an existing structure of the same name.
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.
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); // with the pointer psMesh->addScalarQuantity("some values", values); // by name polyscope::getSurfaceMesh("my mesh")->addScalarQuantity("some values", values);
As before, each structure offers a
get___(name) method, like
getSurfaceMesh(name) which can be used to get pointer to a 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.
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.
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)
removeStructure(Struture*), but accepts a type name and name instead.
void removeStructure(std::string name, bool errorIfAbsent = true)
removeStructure(Struture*), but accepts a name instead. Will fail unless there is exactly one structure with the given name across all structure types.