.. _particle-model-page:

##############
Particle Model
##############

Opening a Particle Model
=========================

The simplest way to open a particle dataset is to provide a file path. The component will select the appropriate reader
based on the file extension (``.ptfx`` or ``.vtp``):

.. code-block:: cpp

    #include "CeeParticleModel/ParticleModel.h"

    cee::pt::Error error;
    cee::PtrRef<cee::pt::ParticleModel> model = new cee::pt::ParticleModel;

    if (!model->open("C:/data/particles.ptfx", &error))
    {
        // Handle error - see Error Handling section below
    }

After a successful call to :func:`open() <cee::pt::ParticleModel::open>`, the model is ready for frame iteration
and visualization.


Adding the Model to a View
==========================

Since :class:`ParticleModel <cee::pt::ParticleModel>` extends :class:`vis::Model <cee::vis::Model>`, you add it to a
:class:`View <cee::vis::View>` just like any other model:

.. code-block:: cpp

    cee::PtrRef<cee::vis::View> view = /* your view */;
    view->addModel(model.get());

    // The model renders as a point cloud; size & color are configurable
    model->setParticleSize(3.0f);
    model->updateVisualization();
    view->requestRedraw();


Model Lifecycle
===============

You can query whether a model is open with :func:`isOpen() <cee::pt::ParticleModel::isOpen>` and explicitly close it
with :func:`close() <cee::pt::ParticleModel::close>`:

.. code-block:: cpp

    if (model->isOpen())
    {
        // Model has an active dataset
        size_t frames = model->frameCount();
    }

    // Explicitly release the dataset and free resources
    model->close();

Calling :func:`close()` releases the reader, clears cached frames, and removes any renderables. The model can be
reopened with a different file afterwards.
