Firefly is an interactive viewer for any particle-based data. A live example is available here or if you're ready to get started creating your own interactive viewer, click here.
If you use Firefly, please cite our ApJS paper and our entry in the Astrophysics Source Code Library (ASCL).
Comprehensive documentation is available here.
If you host Firefly on a server from your own repository — a fork of this one carrying site-specific settings, data and launch scripts — keep it as a fork and merge from here, rather than copying files across. A copy script has to overwrite everything from upstream while preserving your local edits; that is exactly what a merge already does, and it does it correctly.
Run the merge on your own machine. The server only ever pulls.
One-time setup, in your local clone of the deployment repository:
git remote add upstream https://github.com/ageller/Firefly.git
git fetch upstreamIf that repository was ever cloned on Windows it may have CRLF line endings committed,
which makes every line of a file look modified and turns every merge into a conflict.
Fix it once, before the first merge, by copying this repository's .gitattributes into
yours and running:
git add --renormalize .
git commit -m "normalize line endings to LF"To pick up a new Firefly release, still in your local clone of the deployment repository:
git checkout -b sync-upstream # work on a branch, not on the default one
git fetch upstream
git merge upstream/main # resolve any conflicts, then commitTest locally, then merge the branch into your default branch and push it.
git checkout main
git merge --ff-only sync-upstream
git push origin mainOn the server, in the deployment repository:
git pullthen restart whatever serves the app (for example, the gunicorn service).
Merges stay clean for as long as your customizations live in files this repository never touches. Some ways to arrange that:
- Put site-specific choices in your dataset's settings
.jsoninstead of in code. GUI panels can be hidden withGUIExcludeList, a list of GUI paths such as"main/general/data/loadNewData", so hiding a control needs no source change. - To add markup to the
<head>of every page — an analytics tag, extra meta tags — drop atemplates/_extra_head.htmlinto your repository. Every template already includes it if it exists, so you never have to edit the shared templates. - If the instance is exposed on the open internet, run it in public mode: set
FIREFLY_PUBLIC=1in the server's environment (this is the one that works under gunicorn/wsgi) or pass--publicto thefireflycommand. That refuses the endpoints which accept data or settings for a live viewer session, and keeps a single fixed room so visitors are never prompted for a session name. - Keep server-specific launch scripts in their own files.
- Leave packaged files you don't need in place rather than deleting them; deletions become modify/delete conflicts every time upstream edits them.
- Aaron Geller
- Alex Gurvich
- Mike Cronin
- Zach Hafen
- Alessandro Febretti
- Mahlet Shiferaw
- Luolei Zhao
- Nora Linzer
- Claude-André Faucher-Giguère
Firefly is written in WebGL using the three.js library. This tool builds off of a previous version developed by Alessandro Febretti.
This project is funded by Northwestern's Center for Interdisciplinary Exploration and Research in Astrophysics (CIERA), Northwestern's IT Research Computing group, and NSF grants AST-1412836, AST-1715216, and CAREER award AST-1652522 awarded to Claude-André Faucher-Giguère.
Firefly was originally designed for FIRE data, but has since been extended to support any particle data. This package should not be confused with the serendipitously named web-based visualization software Firefly, from Caltech-IPAC, a general tool for retrieving and viewing astronomy data.