Producing Firefly formatted .json files using the Python API

Firefly reads formatted JSON files. While it is certainly possible to produce Firefly formatted .json files manually (with say, a text editor) we have instead provided a convenient Python frontend for users to take advantage of.

The Reader class

A Reader instance serves to link instances of each of the below classes. Its writeToDisk() method will take the data from each of the attached instances and collect it into a single JSONdir, producing each of the necessary files listed in Understanding Firefly’s input requirements automatically.

• Tutorial notebook: Using the Reader class
  • Creating a Reader instance
  • Store the coordinates in a ParticleGroup
  • Outputting to .ffly
  • Using an ArrayReader sub-class

To quickly open your own data, you can sub-class Reader (e.g. firefly.data_reader.SimpleReader) to parse and re-format your data while maintaining all of the inherited functionality that the Reader class offers. Example sub-classes customized for FIRE simulation data ship with Firefly (firefly.data_reader.FIREreader and firefly.data_reader.SimpleFIREreader) and are demonstrated in the corresponding example notebook.

• Convert FIRE data
  • Using firefly.data_reader.SimpleFIREreader

Using with yt

If you are using yt can use the dataset.create_firefly_object method to create a Reader instance. For more information see the Firefly page in the yt documentation.

The ParticleGroup class

ParticleGroup instances organize coordinate array data alongside any corresponding field array data. They also contain lists of boolean flags to signal to the Firefly webapp whether someone who visits the webapp should be allowed to filter and/or colormap by a particular field.

Each ParticleGroup instance gets its own sub-panel in the UI, the contents of which can be customized using a Settings.json file (described below). Filters and colormaps only apply to the particle groups to which they are attached, there are no global filter options.

The Settings class

Settings instances allow users to customize the appearance of the webapp’s UI. Every element of the UI is toggleable and has a corresponding boolean flag.

In this way, custom instances of Firefly can be created to catered to different audiences without having to change any of the Firefly source code.

Note

The appropriate settings can either be passed at the initialization of a firefly.data_reader.Reader or firefly.data_reader.ParticleGroup instance OR can be updated after the fact by accessing the reader.settings or particleGroup.attached_settings attributes.

The firefly.data_reader.Settings documentation provides a comprehensive list of the relevant boolean flags and the UI elements they control.

• Tutorial notebook: Managing Custom Settings
  • Settings can be changed the same way you would change a key in a dictionary
  • Settings are most useful when connected to a firefly.data_reader.Reader object
  • Settings can also be imported from .json files
  • Attaching a ParticleGroup to a Settings

The TweenParams class

A TweenParams instance allows the user to pre-define interpolated camera paths (tweening; from in-betweening) that visitors to the Firefly webapp can activate through the UI (see Camera controls). Keyframe camera locations are specified and are linearly interpolated to produce a smoothly varying camera path within the webapp. This feature is available whenever a JSONdir contains a TweenParams.json file. This file will be produced if a Reader has a TweenParams attached to it when the writeToDisk() method is called.