# 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.

Conversation saved
HOOPSY BETA

### Hello! I'm HOOPSY

Your multilingual generative AI assistant for documentation. Ask me anything about HOOPS Envision for Desktop in your own language, or choose a sample question below to start a conversation:

What is HOOPS Envision for Desktop?
What are the latest release notes for HOOPS Envision for Desktop?
How do I start evaluating HOOPS Envision for Desktop?
How do I write my first sample application?
How can I get assistance?

HOOPSY may store conversations according to OpenAI's policy. Responses may not always be accurate.

HOOPSY is thinking...