.. _particle-frames-scalars-page:

############################
Frame Iteration and Scalars
############################

Frame Iteration and Scalar Fields
==================================

Once a model is open, you can iterate over frames and select scalar fields for visualization:

.. code-block:: cpp

    // Query dataset extents
    size_t numFrames = model->frameCount();
    size_t maxParticles = model->maxParticleCount();
    cee::BoundingBox bbox = model->boundingBox();

    // Move to a specific frame
    model->setCurrentFrameIndex(42);

    // Query the current frame index
    size_t current = model->currentFrameIndex();  // 42

    // Query available scalar fields
    std::vector<cee::Str> fields = model->scalarFieldNames();

    // Activate a scalar field (colors particles by this field)
    model->setActiveScalarField("Temperature");

    // Query the active scalar field
    if (model->hasActiveScalarField())
    {
        cee::Str name = model->activeScalarField();  // "Temperature"
    }

    // Query the scalar range for the current frame
    double minVal, maxVal;
    model->scalarRange(&minVal, &maxVal);

    // Clear scalar coloring (revert to uniform particle color)
    model->clearActiveScalarField();

    // Update the renderable visualization
    model->updateVisualization();


Rendering Properties
====================

You can configure rendering properties such as particle size, color, opacity, and decimation factor:

.. code-block:: cpp

    model->setParticleSize(2.0f);
    model->setParticleColor(cee::Color3f(1.0f, 0.5f, 0.0f));
    model->setOpacity(0.8f);
    model->setDecimation(0.5f);  // Show 50% of particles

    // Query current property values
    float size  = model->particleSize();       // 2.0f
    cee::Color3f col = model->particleColor(); // (1.0, 0.5, 0.0)
    float alpha = model->opacity();            // 0.8f
    float dec   = model->decimation();         // 0.5f

    // Query the actual number of visible particles (after decimation)
    size_t visible = model->visibleParticleCount();

The decimation uses a deterministic hash on particle IDs, so the same subset of particles is shown consistently across
frames. This provides stable visual behavior during animation.

To clear the renderable parts without closing the model (e.g. before rebuilding):

.. code-block:: cpp

    model->clearVisualization();

For diagnostic purposes, :func:`modelInfo() <cee::pt::ParticleModel::modelInfo>` returns a summary string describing
the model state:

.. code-block:: cpp

    cee::Str info = model->modelInfo();
    // e.g. "ParticleModel: 200 frames, 10000 max particles, scalar: Temperature"


Scalar Mapping
==============

To control how scalar values are mapped to colors, assign a
:class:`ScalarMapperContinuousDomain <cee::vis::ScalarMapperContinuousDomain>`:

.. code-block:: cpp

    #include "CeeVisualization/ScalarMapperContinuousDomain.h"

    cee::PtrRef<cee::vis::ScalarMapperContinuousDomain> mapper = new cee::vis::ScalarMapperContinuousDomain;
    mapper->setRange(0.0, 1500.0);
    // Configure color table, etc.

    model->setScalarMapper(mapper.get());
    model->updateVisualization();

You can retrieve the current scalar mapper with :func:`scalarMapper() <cee::pt::ParticleModel::scalarMapper>`:

.. code-block:: cpp

    cee::vis::ScalarMapperContinuousDomain* currentMapper = model->scalarMapper();

When no scalar mapper is set, the component uses a default rainbow mapping over the scalar range.
