firefly.data_reader.Settings

class firefly.data_reader.Settings(settings_filename='Settings.json', **kwargs)[source]

Bases: object

This is a class for organizing the various settings you can pass to Firefly to customize how the app is initialized and what features the user has access to.

It is easiest to use when instances of Settings are passed to a firefly.data_reader.Reader instance when it is initialized.

General settings that affect the app state :param decimate: set the initial global decimation

(e.g, you could load in all the data by setting the decimation_factor to 1 for any individual firefly.data_reader.ParticleGroup, but only _display_ some fraction by setting decimate > 1 here). This is a single value (not a dict), defaults to None

Parameters

  • maxVrange (float, optional) – maximum range in velocities to use in deciding the length of the velocity vectors (making maxVrange larger will enhance the difference between small and large velocities), defaults to 2000.

  • friction (float, optional) – set the initial friction for the controls, defaults to 0.1

  • zmin (float, optional) – set the minimum distance a particle must be to appear on the screen (defines the front edge of the frustum), defaults to 1

  • zmin – set the maximum distance a particle can be to appear on the screen (defines the back edge of the frustum), defaults to 5e10

  • stereo (bool, optional) – flag to start in stereo mode, defaults to False

  • stereoSep (float, optional) – camera (eye) separation in the stereo mode (should be < 1), defaults to 0.06

  • minPointScale (float, optional) – minimum size of particles, defaults to 0.01

  • maxPointScale (float, optional) – maximum size of particles, defaults to 10

  • startFly (bool, optional) – flag to start in Fly controls (if False, then start in the default Trackball controls), defaults to False

  • startTween (bool, optional) – flag to initialize the Firefly scene in tween mode, requires a valid tweenParams.json file to be present in the datadir, defaults to False

  • startVR (bool, optional) – flag to initialize Firefly in VR mode, defaults to False

  • startColumnDensity (bool, optional) – flag to initialize Firefly in the (mostly) experimental column density projection mode, defaults to False

Settings that affect the browser window

Parameters

  • title (str, optional) – the title of the webpage, shows up in browser tab, defaults to ‘Firefly’

  • annotation (str, optional) – text to include at the top of the Firefly window as an annotation, defaults to None

  • controlsExplainerDelay_sec (int, optional) – seconds before the controls explainer auto-hides. If <=0, then the controls explainer is not shown, defaults to 5

  • showFPS (bool, optional) – flag to display the FPS (frames per second) of the Firefly scene, defaults to False

  • showMemoryUsage (bool, optional) – flag to display the memory usage in GB of the loaded data– useful for octrees when memory usage changes over time, defaults to False

  • memoryLimit (float, optional) – maximum memory in bytes to use when loading an octree dataset. If this limit is exceeded then previously loaded nodes will be discarded to bring the memory usage back below. Works best in Chrome which exposes the memory usage directly, otherwise memory usage is only estimated, defaults to 2e9

  • GUIExcludeList (list, optional) – list of string GUI element URLs (e.g. ‘main/general/data/decimation’) to exclude from the GUI. Case insensitive. If None then an empty list, defaults to None

  • collapseGUIAtStart (bool, optional) – flag to collapse the GUI when the app starts up, defaults to True

Settings that affect the position and orientation of the camera

Parameters

  • center (np.ndarray of shape (3), optional) – do you want to explicilty define the initial camera focus/ zero point (if not, the WebGL app will calculate the center as the mean of the coordinates of the first particle set loaded in), defaults to None

  • camera (np.ndarray of shape (3), optional) – initial camera location, NOTE: the magnitude must be >0 , defaults to None

  • cameraRotation (np.ndarray of shape (3), optional) – can set camera rotation in units of radians if you want, defaults to None

  • cameraUp (np.ndarray of shape (3), optional) – set camera orientation (north vector) using a quaternion, defaults to None

  • quaternion (np.ndarray of shape (4), optional) – can set camera rotation using a quaternion of form (w,x,y,z), defaults to None

General settings that affect the state app state

Parameters

  • maxVrange (float, optional) – maximum range in velocities to use in deciding the length of the velocity vectors (making maxVrange larger will enhance the difference between small and large velocities), defaults to 2000.

  • startFly (bool, optional) – flag to start in Fly controls (if False, then start in the default Trackball controls), defaults to False

  • friction (float, optional) – set the initial friction for the controls, defaults to 0.1

  • stereo (bool, optional) – flag to start in stereo mode, defaults to False

  • stereoSep (float, optional) – camera (eye) separation in the stereo mode (should be < 1), defaults to 0.06

  • decimate (int, optional) – set the initial global decimation (e.g, you could load in all the data by setting the decimation_factor to 1 for any individual firefly.data_reader.ParticleGroup, but only _display_ some fraction by setting decimate > 1 here). This is a single value (not a dict), defaults to None

  • start_tween (bool, optional) – flag to initialize the Firefly scene in tween mode, requires a valid tweenParams.json file to be present in the datadir, defaults to False

  • CDmin (float, optional) – bottom of the renormalization for the experimental column density projection mode, defaults to 0

  • CDmax (bool, optional) – top of the renormalization for the experimental column density projection mode, defaults to 1

  • CDlognorm – flag for whether renormalization should be done in log (CDlognorm=1) or linear (CDlognorm=0) space, defaults to 0

  • columnDensity – flag for whether the experimental column density projection mode should be enabled at startup. Toggle this mode by pressing ‘p’ on the keyboard, defaults to 0

Settings that will define the initial values of the particle UI panes

Parameters

  • plotNmax (int, optional) – maximum number of particles to plot This is a dict with keys of the particle UInames mapped to ints, defaults to all particles

  • showVel (dict of UIname:bool, optional) – flag to start showing the velocity vectors This is a dict with keys of the particle UInames mapped to bools, defaults to dict([(UIname,False) for UIname in UInames])

  • velType (dict of UIname:str, optional) – type of velocity vectors to plot. This is a dict with keys of the particle UInames mapped to strs that must be one of ‘line’, ‘arrow’, or ‘triangle’, defaults to dict([(UIname,’line’) for UIname in UInames])

  • color (dict of UIname:list of len = 4, optional) – the default colors for each particle group, This is a dict with keys of the particle UInames mapped to 4-element lists of rgba float values, defaults to random color with a = 1

  • sizeMult (dict of UIname:float, optional) – the default point size multiplier. This is a dict with keys of the particle UInames mapped to floats, defaults to dict([(UIname,1) for UIname in UInames])

  • showParts (dict of UIname:bool, optional) – show particles by default. This is a dict with keys of the particle UInames mapped to bools, defaults to dict([(UIname,True) for UIname in UInames])

  • radiusVariable (dict of UIname:int, optional) – dict of UIname:int which are indices for which variable to scale the radius by (if any have been flagged as allowable to be a radius scale). 0 is always ‘None’ and will make all particles the same radius, optional defaults to dict([(UIname,0) for UIname in UInames])

Settings used to define properties of the velocity vector field

which can also be used to extrapolate new positions using the animateVel kwarg.

Parameters

  • showVel (dict of UIname:bool, optional) – flag to start showing the velocity vectors This is a dict with keys of the particle UInames mapped to bools, defaults to dict([(UIname,False) for UIname in UInames])

  • velType – type of velocity vectors to plot. This is a dict with keys of the particle UInames mapped to strs that must be one of ‘line’, ‘arrow’, or ‘triangle’, defaults to dict([(UIname,’line’) for UIname in UInames])

  • velVectorWidth (dict of UIname:float, optional) – width of the velocity vectors, defaults to dict([(UIname,1) for UIname in UInames])

  • velGradient (dict of UIname:bool, optional) – flags for whether there should be a gradient to white applied along the length of the velocity vector to indicate direction, defaults to dict([(UIname,False) for UIname in UInames])

  • animateVel (dict of UIname:bool, optional) – flags for whether velocity extrapolation should be enabled at startup, defaults to dict([(UIname,False) for UIname in UInames])

  • animateVelDt (dict of UIname:float, optional) – DT for which to increment the extrapolation defaults to dict([(UIname,0) for UIname in UInames])

  • animateVelTmax (dict of UIname:float, optional) – maximum time to extrapolate before resetting particles to their original positions defaults to dict([(UIname,1) for UIname in UInames])

Settings that will define the initial values of the filters in the particle UI panes and consequently what particles are filtered at startup.

Parameters

  • filterLims (dict of UIname:dict of field:[min,max] range, optional) – initial [min, max] limits to the filters. This is a nested dict of the particle UInames, then for each filterble field the [min, max] range (e.g., {‘Gas’:{‘log10Density’:[0,1],’magVelocities’:[20, 100]}}), defaults to None and is set in the web app to [min, max] of that field

  • filterVals (dict of UIname:dict of field:[min,max] range, optional) – initial location of the filter slider handles. This is a nested dict of the particle UInames, then for each filterble field the [min, max] range (e.g., {‘Gas’:{‘log10Density’:[.1,0.5],’magVelocities’:[50, 60]}}), defaults to None and is set in the web app to [min, max] of that field

  • invertFilter (dict of UIname:dict of field:bool, optional) – flags for whether filters should _hide_ particles within their range (True) or not (False), defaults to UIname:dict of field:False

Settings that will define the initial values of the colormaps in the particle UI panes.

Parameters

  • colormapLims (dict of UIname:dict of field:[min,max] range, optional) – initial [min, max] limits to the colormaps. This is a nested dict of the particle UInames, then for each colormappable field the [min, max] range (e.g., {‘Gas’:{‘log10Density’:[0,1],’magVelocities’:[20, 100]}}), defaults to None and is set in the web app to [min, max] of that field

  • colormapVals (dict of UIname:dict of field:[min,max] range, optional) – initial location of the colormap slider handles. This is a nested dict of the particle UInames, then for each colormappable field the [min, max] range (e.g., {‘Gas’:{‘log10Density’:[.1,0.5],’magVelocities’:[50, 60]}}), defaults to None and is set in the web app to [min, max] of that field

  • colormap (dict of UIname:float, optional) – index of the colormap to use for each gas particle, defined by the grid of colors in firefly/static/textures/colormap.png TODO: (index + 0.5) * (8/256) This is a dict with keys of the particle UInames mapped to floats, (e.g. {‘Gas’:0.015625, ‘Stars’:0.015625}), defaults to first colormap

  • colormapVariable (dict of UIname:int, optional) – index in arrays_to_track of array to colormap by This is a dict with keys of the particle UInames mapped to ints, (e.g. {‘Gas’:0, ‘Stars’:0}), defaults to 0

  • showColormap – flags for whether the colormap should be initialized

at startup.

This is a dict with keys of the particle UInames mapped to bools, (e.g. {‘Gas’:False, ‘Stars’:False}), defaults to False

Parameters

  • blendingMode (dict of UIname:str, optional) – blending mode for each particle group, options are: ‘additive’,’normal’,’subtractive’,’multiplicative’,’none’. This is a dict with keys of the particle UInames mapped to strs, (e.g. {‘Gas’:’additive’, ‘Stars’:’additive’}), defaults to ‘additive’

  • depthTest (dict of UIname:bool, optional) – flags for whether the depth checkbox should be checked at startup. This is a dict with keys of the particle UInames mapped to bools, (e.g. {‘Gas’:False, ‘Stars’:False}), defaults to False

__getitem__(key)[source]

Implementation of builtin function __getitem__

Parameters

key (str) – key to read

Returns

attr, the value from the settings dictionary

Return type

object

__init__(settings_filename='Settings.json', **kwargs)[source]
Base initialization method for Settings instances. A Settings will store

the app state and produce firefly compatible .json files.

Parameters

settings_filename (str, optional) – name of settings .json file, defaults to ‘Settings.json’

__setitem__(key, value)[source]

Implementation of builtin function __setitem__

Parameters

  • key (str) – key to set

  • value (object) – value to set to key

__weakref__

list of weak references to the object (if defined)

attachSettings(particleGroup)[source]

Adds a ParticleGroup’s settings to the relevant settings dictionaries.

Parameters

particleGroup (firefly.data_reader.ParticleGroup) – the ParticleGroup that you want to link to this Settings.

keys()[source]

Returns a list of keys for all the different settings sub-dictionaries

loadFromJSON(filename, loud=True)[source]

Replaces the current settings with those stored in a JSON file.

Parameters

  • filename (str) – full filepath to settings .json file

  • loud (bool, optional) – flag to print status information to the console, defaults to True

Raises

FileNotFoundError – if the specified filename does not exist

outputToDict()[source]
Returns

all_settings_dict, concatenated settings dictionary

Return type

dict

outputToJSON(datadir, file_prefix='', filename=None, loud=True, write_to_disk=True, not_reader=True)[source]

Saves the current settings to a JSON file.

Parameters

  • datadir (str, optional) – the sub-directory that will contain your JSON files, relative to your $HOME directory. , defaults to $HOME/<file_prefix>

  • file_prefix (str, optional) – Prefix for any .json files created, .json files will be of the format: <file_prefix><filename>.json, defaults to ‘Data’

  • filename (str, optional) – name of settings .json file, defaults to self.settings_filename

  • file_prefix – string that is prepended to filename, defaults to ‘’

  • loud (bool, optional) – flag to print status information to the console, defaults to True

  • write_to_disk (bool, optional) – flag that controls whether data is saved to disk (True) or only converted to a string and returned (False), defaults to True

  • not_reader – flag for whether to print the Reader filenames.json warning, defaults to True

Returns

filename, JSON(all_settings_dict) (either a filename if written to disk or a JSON strs)

Return type

str, str

printKeys(pattern=None, values=True)[source]

Prints keys (and optionally their values) to the console in an organized (and pretty) fashion.

Parameters

  • pattern (str, optional) – string that settings group must contain to be printed, defaults to None

  • values (bool, optional) – flag to print what the settings are set to, in addition to the key, defaults to True