Visualizer for darkness readings collected by Unihedron Sky Quality Meters.
Works with files in the 'International Dark Sky Association (IDA) NSBM Community Standards for Reporting Skyglow Observations' format and files in the format output by the Unihedron software feature 'sun-moon-mw-clouds'.
The software can be run as a web application or standalone (no server).
The SQM Visualizer software is free and open-source, provided as-is and licensed under the GNU Affero General Public License version 3, or (at your option) any later version. The software was designed and developed by Darren Creutz.
While absolutely not mandatory, if you install the software on a public website and/or find it useful, the author would appreciate a quick email to dcreutz@dcreutz.com letting him know.
Many features are documented in the user guide contributed by Alan Creutz.
-
Download the standalone SQM Visualizer and extract the zip file.
-
Open sqm_visualizer.html in your browser (most likely this just means double click on the file, alternatively open a new tab/window in your browser and drag the file into it).
-
When prompted, select the data files on your computer (multiple files can be selected simultaneously).
-
Extract the tar.gz file and place the contents in a directory on your web server.
-
Copy (or symlink) your SQM data files into the data directory.
-
[Recommended] Make the cache directory writeable by the web server user. On shared hosting, this is often automatic; on a typical linux server, use chown to set the owner of the cache directory to www or www-data.
-
[Optional] If you have a camera taking images of the sky, copy (or symlink) the images in to the images directory. The directory structure expected is images/YYYY-MM/YYYY-MM-DD/image-file-name, see the SQM Data Retriever configuration instructions for more information.
-
[Optional] If you have images and would like the backend to automatically create thumbnails, make the resized_images directory writeable by the web server user.
-
[Optional] Edit config.js to customize your installation. See the SQM Visualizer configuration instructions for more information.
-
[Optional] Edit config.php to customize your installation. See the SQM Data Retriever configuration instructions for more information.
-
[Optional] If using a large dataset, particularly if regression analysis and images are involved, run the included command line script bin/update_cache_cli.php (see below).
-
[Optional] Create .info files in each data directory specifying information about the SQM. The file should be named .info and have the structure
Name: My SQM Device
Latitude: 30.1234
Longitude: -110.6789
Elevation: 100.2
- Go to http(s)://your-server/sqm-directory/index.php in your browser. If cacheing is enabled, the first run make take some time to initially build the cache.
The backend can work with a single SQM's data or with that of multiple SQMs. If using a single SQM, simply place the data files in the data directory. If working with multiple SQMs, create a subdirectory inside the data directory for each SQM and place its data files in that directory.
If cacheing is not enabled, the backend relies on the data files to be named in such a way that indicates the month(s) of data they contain. Therefore, they must be named in such a way as to include YYYY-MM or YYYYMM somewhere in their name for each month they have data for.
If cacheing is enabled, the file names can be anything.
Browser callable script to clear the cache. Disabled by default, to enable it, edit the .php file and change the line $disable = true; to $disable = false;. Ideally an unnecessary script but included since cache corruption can occur when server connectivity is interrupted.
Command line script to clear the cache. This script can only be run when in the directory containing sqm.php.
Command line script to update the cache. This script can only be run when in the directory containing sqm.php.
When working with large datasets, and most especially when resizing images, this script should be used prior to the first browser call to the backend.
Note that this script must be run as the same server user as the web server runs as, or after running it, the cache (the cache directory and all files inside it) must be manually set to be writeable by the web user.
Optionally, a cron job can be configured to periodically update the cache using a cron.d file (or crontab entry) similar to
5 * * * * www-data cd /var/www/html; ./bin/update_cache_cli.php
If you have data files for more than about five SQMs, you may wish to take advantage of the configuration option enabledSqms (see the configuration instructions) to only enable some of them and have a dropdown list allowing the user to select which subset are displayed in the chart.
The server backend, included in the distribution files for the SQM Visualizer, is the SQM Data Retriever. While developed exclusively to process data files for the SQM Visualizer, the SQM Data Retriever is a standalone server application with a full API and may be of use for other applications.
The software works well in conjunction with PySQM performing the actual data collection. The simplest method of combining the two is to run PySQM creating monthly data files and symlink the directory containing the monthly data files to the data directory in the visualizer directory.
Thanks to chart.js, chartjs-datefns-adapter, dateFns, flatpickr, multiselect, papaparse, suncalc and suncalc-php. Thanks to Bill Kowalik for sharing his regression analysis code which the SQM Data Retriever's regression algorithm is loosely based on.
The SQM Visualizer software is licensed under the GNU Affero General Public License version 3 (at your option any later version) and, as such, is free and open-source.
If you wish to incorporate it or its components (including the SQM Data Retriever) in a substantial way in software not sharing that or a similar license, a dual licensing scheme may be arranged at the discretion of the author of the code/owner of the copyright.