cee::pt::ParticleModel

class ParticleModel : public Model

ParticleModel is a subclass of Model for time-stepped particle data.

It connects the CeeParticleModel file readers to the visualization pipeline, rendering particles as GL_POINTS with optional per-vertex scalar coloring.

Open a particle dataset with open(). The format is auto-detected from the file extension. To use a custom ParticleDatasetReader subclass, call the open(std::unique_ptr<ParticleDatasetReader>) overload with an already-opened reader. Use setActiveScalarField() to enable scalar coloring and setScalarMapper() to control the color mapping.

Property setters (setParticleSize(), setParticleColor(), etc.) automatically update the visualization. A call to updateVisualization() is only needed to force a full refresh.

cee::PtrRef<cee::pt::ParticleModel> model = new cee::pt::ParticleModel;
model->open("path/to/dataset.ptfx");
view.addModel(model.get());

See also

vis::Model, ParticleDatasetReader

Public Functions

ParticleModel()

Constructs an empty model.

bool open(const Str &filePath, Error *error = nullptr)

Opens a particle dataset file.

Auto-detects .ptfx vs .vtp format.

Returns true on success. If error is non-null, the error code is set on failure.

See also

open(std::unique_ptr<ParticleDatasetReader>, Error*)

bool open(std::unique_ptr<ParticleDatasetReader> reader, Error *error = nullptr)

Opens a particle model with a caller-supplied ParticleDatasetReader.

The reader must already be successfully opened before passing it here. Ownership is transferred to the model. Any previously open dataset is closed first.

This overload enables custom ParticleDatasetReader subclasses to be used with ParticleModel, supporting file formats beyond the built-in .ptfx and .vtp readers.

auto reader = std::make_unique<MyCustomReader>();
reader->open("path/to/data.xyz");

cee::PtrRef<cee::pt::ParticleModel> model = new cee::pt::ParticleModel;
model->open(std::move(reader));
view.addModel(model.get());

Returns true on success. If error is non-null, the error code is set on failure.

See also

ParticleDatasetReader, open(const Str&, Error*)

void close()

Closes the dataset and releases all resources.

bool isOpen() const

Returns true if a dataset is currently open.

size_t frameCount() const

Returns the total number of frames in the dataset.

size_t maxParticleCount() const

Returns the maximum particle count across all frames.

size_t visibleParticleCount() const

Returns the number of particles currently rendered (after decimation)

virtual BoundingBox boundingBox()

Returns the bounding box of the entire dataset.

size_t currentFrameIndex() const

Returns the index of the current frame.

Returns UNDEFINED_SIZE_T if no frames are present.

bool setCurrentFrameIndex(size_t frameIndex, Error *error = nullptr)

Sets the current frame (the frame to render).

frameIndex must be [0 .. frameCount() - 1]. Returns true if the frame was loaded successfully. If error is non-null, the error code is set on failure.

std::vector<Str> scalarFieldNames() const

Returns the list of available scalar field names.

Str activeScalarField() const

Returns the currently active scalar field name (empty string if none)

bool hasActiveScalarField() const

Returns true if a scalar field is currently active.

bool setActiveScalarField(const Str &fieldName)

Sets the active scalar field.

Returns false if the field name is unknown.

The current frame is re-read to pick up the new scalar values.

void clearActiveScalarField()

Clears the active scalar field, reverting to solid color rendering.

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

Returns the scalar range of the active field across all frames.

Returns true if the range is valid. Returns false if no scalar field is active or the range has not yet been computed.

bool updateVisualization(Error *error = nullptr)

Updates the visualization based on the current settings.

Forces a full refresh. Property setters already update the visualization automatically, so this is only needed after external data changes.

Returns false if the dataset is not open or no frame data is available.

void clearVisualization()

Clears visualization.

void setScalarMapper(vis::ScalarMapperContinuousDomain *mapper)

Sets the scalar mapper used for per-vertex scalar coloring.

Warning

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

vis::ScalarMapperContinuousDomain *scalarMapper() const

Returns the current scalar mapper.

void setParticleSize(float size)

Sets the particle point size (in pixels)

float particleSize() const

Returns the current particle point size.

void setParticleColor(const Color3f &color)

Sets the uniform particle color.

Color3f particleColor() const

Returns the current uniform particle color.

void setOpacity(float opacity)

Sets the per-model opacity (0.0 = fully transparent, 1.0 = fully opaque)

float opacity() const

Returns the current per-model opacity.

void setDecimation(float factor)

Sets the decimation factor for particle rendering.

A factor of 1.0 (default) shows all particles, 0.5 shows approximately half, 0.0 shows none. The same particles survive decimation across frames to avoid flickering during animation.

float decimation() const

Returns the current decimation factor (0.0 = show nothing, 1.0 = show all)

void setCacheMemoryLimit(size_t maxBytes)

Sets the maximum amount of memory (in bytes) the frame cache may consume.

Can be called before or after open(). Default is 5 GB.

size_t cacheMemoryLimit() const

Returns the current cache memory limit (in bytes)

size_t cacheCurrentMemoryBytes() const

Returns the total memory currently consumed by cached frames (in bytes)

void preloadFrames(size_t startFrame, size_t count)

Pre-reads frames into the internal cache for lookahead during animation playback.

virtual Str modelInfo() const

Returns info regarding the current model contents.