.. role:: ts-api-decorator

#############
ParticleModel
#############

.. js:module:: cee.pt
   :noindex:

.. container:: ts-api-section

   .. js:class:: ParticleModel

      Client-side particle model. Fetches, decodes, caches, and renders time-stepped
      particle frames via the PtServer REST API (``/api/v1/models``).


      .. code-block:: typescript

         const model = new cee.pt.ParticleModel();
         await model.openModel('http://server/api/v1/models/mydata.ptfx');
         await model.setFrame(0);
         model.closeModel();




.. container:: api-index-section

   .. rubric:: Constructors

   .. rst-class:: api-index-list-item api-kind-constructor api-parent-kind-class

   * :js:meth:`~cee.pt.ParticleModel.constructor`



.. container:: api-index-section

   .. rubric:: Accessors

   .. rst-class:: api-index-list-item api-kind-accessor api-parent-kind-class

   * :js:attr:`~cee.pt.ParticleModel.activeScalarField`
   * :js:attr:`~cee.pt.ParticleModel.animation`
   * :js:attr:`~cee.pt.ParticleModel.currentFrameIndex`
   * :js:attr:`~cee.pt.ParticleModel.datasetInfo`
   * :js:attr:`~cee.pt.ParticleModel.frameCount`
   * :js:attr:`~cee.pt.ParticleModel.maxParticleCount`
   * :js:attr:`~cee.pt.ParticleModel.name`
   * :js:attr:`~cee.pt.ParticleModel.scalarFieldNames`



.. container:: api-index-section

   .. rubric:: Methods

   .. rst-class:: api-index-list-item api-kind-method api-parent-kind-class

   * :js:meth:`~cee.pt.ParticleModel.closeModel`
   * :js:meth:`~cee.pt.ParticleModel.getBoundingBox`
   * :js:meth:`~cee.pt.ParticleModel.getCurrentFrameScalarRange`
   * :js:meth:`~cee.pt.ParticleModel.getDecimationFactor`
   * :js:meth:`~cee.pt.ParticleModel.getDefaultCameraConfig`
   * :js:meth:`~cee.pt.ParticleModel.getOpacity`
   * :js:meth:`~cee.pt.ParticleModel.getParticleColor`
   * :js:meth:`~cee.pt.ParticleModel.getParticleSize`
   * :js:meth:`~cee.pt.ParticleModel.getScalarMapper`
   * :js:meth:`~cee.pt.ParticleModel.getUseScalarMapping`
   * :js:meth:`~cee.pt.ParticleModel.isOpen`
   * :js:meth:`~cee.pt.ParticleModel.openModel`
   * :js:meth:`~cee.pt.ParticleModel.setActiveScalarField`
   * :js:meth:`~cee.pt.ParticleModel.setDecimationFactor`
   * :js:meth:`~cee.pt.ParticleModel.setFrame`
   * :js:meth:`~cee.pt.ParticleModel.setOpacity`
   * :js:meth:`~cee.pt.ParticleModel.setParticleColor`
   * :js:meth:`~cee.pt.ParticleModel.setParticleSize`
   * :js:meth:`~cee.pt.ParticleModel.setPreloadFrameCount`
   * :js:meth:`~cee.pt.ParticleModel.setScalarMapper`
   * :js:meth:`~cee.pt.ParticleModel.setServerErrorHandler`
   * :js:meth:`~cee.pt.ParticleModel.setUseScalarMapping`





------------

Constructors
============

.. container:: ts-api-section

   .. js:function:: ParticleModel.constructor([ properties])

      :param properties: :ts-api-decorator:`optional` None
      :type properties: Partial <ParticleModelProperties>


      :rtype: ParticleModel



Accessors
=========

.. container:: ts-api-section

   .. js:function:: ParticleModel.activeScalarField()



      :rtype: string



.. container:: ts-api-section

   .. js:function:: ParticleModel.animation()



      The animation controller for this model.


      :rtype: Animation



.. container:: ts-api-section

   .. js:function:: ParticleModel.currentFrameIndex()



      :rtype: number



.. container:: ts-api-section

   .. js:function:: ParticleModel.datasetInfo()



      :rtype: DatasetInfo



.. container:: ts-api-section

   .. js:function:: ParticleModel.frameCount()



      :rtype: number



.. container:: ts-api-section

   .. js:function:: ParticleModel.maxParticleCount()



      :rtype: number



.. container:: ts-api-section

   .. js:function:: ParticleModel.name()



      Name of the model. 

      Mainly used for debugging.


      :rtype: string

   .. js:function:: ParticleModel.name( value)

      :param value: None
      :type value: string


      Name of the model. 

      Mainly used for debugging.


      :rtype: void



.. container:: ts-api-section

   .. js:function:: ParticleModel.scalarFieldNames()



      :rtype: [string]



Methods
=======

.. rst-class:: ts-api-section

closeModel
----------

.. js:method:: ParticleModel.closeModel()



   Close the model and release resources. Error handler is preserved.


   :rtype: void

.. rst-class:: ts-api-section

getBoundingBox
--------------

.. js:method:: ParticleModel.getBoundingBox([ options])

   :param options: :ts-api-decorator:`optional` None
   :type options: ModelBoundingBoxOptions


   Returns the current ``BoundingBox`` (in world coordinates) of the model.

   When called without any parameters this method will return the current bounding box of the model, including only
   visible parts/objects. For models that support it, the full bounding box can may queried by specifying the 
   optional ``ModelBoundingBoxOptions`` and setting ``ModelBoundingBoxOptions.includeHiddenParts`` to true.


   :rtype: BoundingBox

.. rst-class:: ts-api-section

getCurrentFrameScalarRange
--------------------------

.. js:method:: ParticleModel.getCurrentFrameScalarRange()



   Per-frame scalar range de-quantized from uint16 via the global range.


   :rtype: function

.. rst-class:: ts-api-section

getDecimationFactor
-------------------

.. js:method:: ParticleModel.getDecimationFactor()



   :rtype: number

.. rst-class:: ts-api-section

getDefaultCameraConfig
----------------------

.. js:method:: ParticleModel.getDefaultCameraConfig()



   Can return an optional default camera configuration for this model.

   If a model returns a default camera config, any views displaying the model may utilize the information to do first-time
   setup of their camera. The camera config will not have any effect on views where the camera has already been set by the user.
   If multiple models are shown in the same view, the first model with a default camera config will take precedence.


   :rtype: CameraConfig

.. rst-class:: ts-api-section

getOpacity
----------

.. js:method:: ParticleModel.getOpacity()



   Get the opacity of the particles. 0 = fully transparent, 1 = fully opaque.


   :rtype: number

.. rst-class:: ts-api-section

getParticleColor
----------------

.. js:method:: ParticleModel.getParticleColor()



   :rtype: Color3Like

.. rst-class:: ts-api-section

getParticleSize
---------------

.. js:method:: ParticleModel.getParticleSize()



   :rtype: number

.. rst-class:: ts-api-section

getScalarMapper
---------------

.. js:method:: ParticleModel.getScalarMapper()



   :rtype: ScalarMapper

.. rst-class:: ts-api-section

getUseScalarMapping
-------------------

.. js:method:: ParticleModel.getUseScalarMapping()



   :rtype: boolean

.. rst-class:: ts-api-section

isOpen
------

.. js:method:: ParticleModel.isOpen()



   :rtype: boolean

.. rst-class:: ts-api-section

openModel
---------

.. js:method:: ParticleModel.openModel( datasetUrl)

   :param datasetUrl: None
   :type datasetUrl: string


   Open a particle dataset from a URL.


   :rtype: Promise <DatasetInfo>

.. rst-class:: ts-api-section

setActiveScalarField
--------------------

.. js:method:: ParticleModel.setActiveScalarField( fieldName)

   :param fieldName: None
   :type fieldName: string


   Switch active scalar field on the server. Invalidates cache and reloads current frame.


   :rtype: Promise <void>

.. rst-class:: ts-api-section

setDecimationFactor
-------------------

.. js:method:: ParticleModel.setDecimationFactor( factor)

   :param factor: None
   :type factor: number


   Set server-side decimation factor [0.01, 1.0]. Invalidates cache and reloads current frame.


   :rtype: void

.. rst-class:: ts-api-section

setFrame
--------

.. js:method:: ParticleModel.setFrame( frameIndex)

   :param frameIndex: 0-based index in ``[0, frameCount)``
   :type frameIndex: number


   Load and display a frame. Cancels any previous inflight request.


   :rtype: Promise <void>

.. rst-class:: ts-api-section

setOpacity
----------

.. js:method:: ParticleModel.setOpacity( opacity)

   :param opacity: None
   :type opacity: number


   Set the opacity of the particles (clamped to [0, 1]).


   :rtype: void

.. rst-class:: ts-api-section

setParticleColor
----------------

.. js:method:: ParticleModel.setParticleColor( color)

   :param color: None
   :type color: Color3Like


   Set solid particle color (used when scalar mapping is off).


   :rtype: void

.. rst-class:: ts-api-section

setParticleSize
---------------

.. js:method:: ParticleModel.setParticleSize( size)

   :param size: None
   :type size: number


   Set point size in pixels (clamped to >= 1).


   :rtype: void

.. rst-class:: ts-api-section

setPreloadFrameCount
--------------------

.. js:method:: ParticleModel.setPreloadFrameCount( count)

   :param count: None
   :type count: number


   Set the number of frames to preload ahead. 0 disables preloading.
   Takes effect immediately: if the model is open and a frame is loaded,
   a new preload batch is started from the current frame.


   :rtype: void

.. rst-class:: ts-api-section

setScalarMapper
---------------

.. js:method:: ParticleModel.setScalarMapper( mapper)

   :param mapper: None
   :type mapper: ScalarMapper


   Set scalar mapper for color mapping.


   :rtype: void

.. rst-class:: ts-api-section

setServerErrorHandler
---------------------

.. js:method:: ParticleModel.setServerErrorHandler( handler)

   :param handler: None
   :type handler: ServerErrorHandler


   Set error handler. Persists across close/open cycles. Pass ``null`` to clear.


   :rtype: void

.. rst-class:: ts-api-section

setUseScalarMapping
-------------------

.. js:method:: ParticleModel.setUseScalarMapping( enable)

   :param enable: None
   :type enable: boolean


   Enable or disable scalar-based color mapping.
   Toggles the server wire format between 12 BPP (scalar) and 10 BPP (position-only).


   :rtype: Promise <void>

