Code structure

The structure of the Pi Gazing software

This pages gives an overview of the structure of the code on this GitHub repository. It is intended for those who would like to understand how the software works in more detail.

The code is in the src directory of this repository.

The initialisation directory

This contains the database schema used to store Pi Gazing observations.

The script deploy_raspberry_pi.py is used to go through the complete process of setting up a Pi Gazing installation on a Raspberry Pi (assuming you have already followed the installation instructions. It performs tasks including setting up the local database, creating the user account that the software uses, etc.

If you wish to clear out your database of observations, you can run clear_database.sh to do so.

The cmd_line_reports directory

These scripts are not used in the normal operation of a Pi Gazing camera, but provide command line reports of the contents of the database. For example, you can call up a list of images recorded in the last 24 hours, or view them using the quick image viewer (qiv).

The cmd_line_admin directory

These scripts are not used in the normal operation of a Pi Gazing camera, but are used for configuration purposes.

update_observatory_status.py is used to set up or reconfigure an observatory profile in the database, which details the model of camera and lens being used by that observatory. It also sets up the default latitude and longitude of the observatory, which is assumed whenever GPS data is not available.

update_user.py is used to set up user accounts which are used to log into the Meteor Pi web interface. They are also used to authentication when a remote Meteor Pi system attempts to upload observations into the database.

update_regions.py is used to define a clipping mask used by the motion sensor. The motion sensor ignores any moving objects that lie outside the clipping region, which can be useful if foreground objects fall within the camera's field of view. The clipping region should be defined as a series of polygons.

The observatory_control directory

This directory contains the scripts which manage the day-to-day running of a Meteor Pi camera. The main entry point for these script is observe.sh, which simultaneously launches the scripts main.py and load_monitor.py.

The former actually manages to camera's observing cycle, which the other updates LEDs using the Raspberry Pi's GPIO interface to provide a visual indication of whether the camera is working.

The hardware_diagnostics directory

The scripts in here are used for manually controlling a Meteor Pi camera during commissioning. You can flip the relay to turn the camera on or off, and you can call up a live view of what the camera is seeing using mplayer. You can take a long-exposure still photograph using snapshot.sh to check the noise level on long exposures.

The observatory_website directory

This contains the web interface to MeteorPi, implemented in PHP and Javascript. You can use this to browse the images your camera has taken.

You need to run build/build.py to compile the contents of the php subdirectory into a dist directory, which you should then serve using a web server such as Apache.

Your web server also needs to be configured to serve the Pi Gazing AJAX API via the web address https://your.webserver.com/api. This API is provided by the Python module pigazing_helpers.obsarchive.obsarchive_server (see below).

The pigazing_helpers directory

This contains a python module which contains the core classes and subroutines needed for the Pi Gazing software to work.

pigazing_helpers.obsarchive.obsarchive_model contains a series of classes which represent Meteor Pi objects, e.g. observatories, observations and file records.

pigazing_helpers.obsarchive.obsarchive_db provides helper functions for interfacing Python code with the Meteor Pi database. These include looking up records from the database, and returning them as Python objects. Or taking Python objects, and registering them in the database.

pigazing_helpers.obsarchive.obsarchive_server provides an AJAX API to the Meteor Pi database via Flask.

pigazing_helpers.obsarchive.obsarchive_client provides a light-weight Python interface library for looking up observations on a remote server. It is not used by the Meteor Pi server, but is the module that you might use on a remote machine to write python code to automatically query a Meteor Pi server.

The camera_properties directory

This contains a pair of XML files which detail the properties of all of the camera models and lenses in use. This includes, for example, the size of the frame in pixels, and the barrel distortion that each lens produces.

If you decide to use a lens other than one of the ones already defined, you need to create new entries in these XML files. When you set up your observatory with cmd_line_admin/update_observatory_status.py you need to ensure the lens and sensor name match entries in these XML files.

Some of the parameters -- e.g. the Barrel distortion parameters -- may be initially unknown. In this case, set them to zero.

The lens_calibration directory

This contains tools for calculating the barrel distortion present in lenses. Many cheap wide-angle lenses of the kind used in Meteor Pi installations have very bad distortions. This means that the cameras may not be able to work out what direction they are pointing in, because star patterns become unrecognisable.

This can be corrected for be setting the parameters barrel_a, barrel_b and barrel_c which correct for barrel distortion. However, these first need to be determined for your lens.

The tool calibrate-lens.py does this, taking an image file and a list of the pixel positions of stars that you have identified. You should aim to identify at least 20 stars, broadly spread across the image, to ensure an accurate fit.

The image_projection directory

This contains a collection of utilities for manipulating black-and-white PNG files.