Startrails

A startrail image shows the apparent paths of stars across the sky over an extended period of time. It is created by combining many individual images taken sequentially, typically over several hours, and stacking them so that each star’s movement forms a continuous arc.

These arcs are caused by the rotation of the Earth, which makes the stars appear to move around the celestial poles. The length of each trail corresponds to the duration of time covered by the images, while the curvature and direction of the trails depend on the camera’s orientation and the observer’s latitude.

In an Allsky context, startrails are used to:

Illustrate Earth’s rotation in a visually intuitive way.
Summarise an entire night of observations in a single image.
Reveal cloud interruptions, gaps in imaging, or camera downtime.
Highlight the position of the celestial pole and overall sky coverage.
Highlight, meteor and aircraft trails.

Startrail images provide both scientific and aesthetic value, turning many hours of sky monitoring into a single, easily interpreted visual record.

Info

Be default, daytime and nighttime images are looked at when creating a startrails. Typically the daytime images are too bright and are rejected, but it takes time to do that. The startrails Night images only setting can be used to only look at night images. Typically you'll want to enable that setting.

Warning

Only images that are saved are included in a startrails, so if you don't save your nightime images, they won't be included.

Creating a Startrail¶

To have a startrails image automatically created at the end of each night, enable the Generate setting in the Startrails sub-section of the WebUI.

To manually create a startrails image run the generateForDay.sh command. For example, to create and then upload a startrails to any Allsky Website and/or remote server you have for July 10, 2025:

generateForDay.sh --startrails 20250710
generateForDay.sh --upload --startrails 20250710

If you want to experiment using other settings you can specify those settings as such:

generateForDay.sh --startrails 20240710 --startrails-params "--brightness 0.15 -o ~/allsky/tmp/test.jpg"

This will use a Brightness Threshold of 0.15 and put the resulting startrails in ~/allsky/tmp/test.jpg.

Make sure the extra parameters are enclosed in quotes.

See the Advanced section below for the possible parameters you can specify.

Advanced users: running the startrails program manually

generateForDay.sh calls the startrails program to actually create the startrails, passing it several required arguments (the underlined ones below), plus any others you add to the Startrails Extra Parameters setting.

Executing the startrails manually is possible, but not very useful.

``` Usage: startrails [-v] -i | -d -e \ [-b -o | -S][-D ] \ [-s ][-Q ] [-q ]

Arguments: -h | --help : display this message, then exit. -v | --verbose : increase log verbosity. -S | --statistics : print image directory statistics without producing image. -i | --images : file containing list of images to process. If the file also contains the mean brightness for an image, it will be used. -d | --directory : directory from which to read images. If --images is specified then --directory is not needed unless. one or more image names does not start with a '/'.. -D | --output-data : save per-image summary data to the specified file. -e | --extension : filter images to just this extension. -Q | --max-threads : limit maximum number of processing threads (all cpus). -q | --nice-level : nice(2) level of processing threads (10). -o | --output : output image filename. -s | --image-size x : restrict processed images to this size. -b | --brightness : ranges from 0 (black) to 1 (white). (0.35). A moonless sky may be as low as 0.05 while full moon can be as high as 0.4. ```

Example of running the startrails program manually:

cd ~/allsky/bin ./startrails -d images/20250710 -e jpg -b 0.15 -o images/20250710/startrails/startrails.jpg

Startrails settings¶

The only configuration setting for startrails is Brightness Threshold. Images have an average, or "mean" brightness level from 0.0 (pure black) to 1.0 (pure white). The default Brightness Threshold is 0.1 which is a fairly dark image, typical of a moon-less night.

Any image with an average brightness greater than the Brightness Threshold is skipped during startrails generation, so daytime images should be skipped. You need to experiment with this setting to get the best results, as allsky cameras, lenses, and sky conditions impact an image's average brightness, and hence what you use for this setting. Every time a startrails image is created a summary of brightness values is saved to the Allsky database.

If you aren't seeing trailed stars in your images and you get a message like "No images below threshold 0.100, writing the minimum image only", your images are too bright and Brightness Threshold needs to be reduced. To determine what number to use you need to know the typical nighttime sky brightness value. Do the following:

Run allsky-config get_startrails_info to see what your brightness values are.

If there is no data yet a message will appear with a possible reason, otherwise the output will look like:

Startrails date        Minimum   Maximum   Mean      Median    Images used   Not used  Threshold
------------------------------------------------------------------------------------------------
2026-01-17  06:20:45   0.084     0.146     0.103     0.105     250           3         0.15
2026-01-18  06:16:18   0.045     0.135     0.102     0.106     247           6         0.15
------------------------------------------------------------------------------------------------
Averages               0.065     0.140     0.103     0.106     497           9         -

1 entry not used due to invalid data.

Note

Note that the Mean brightness is determined by looking at the whole image, including any black areas. This number is likely different from the mean brightness that can be overlayed onto your images, which is determined by looking at the central portion of an image.

If you crop your image, add a mask to it, or change cameras you'll most likely need to update the Brightness Threshold setting.

Set the Brightness Threshold to the Maximum, or slightly below it. If you have an Averages line, use its Maximum.

Create test startrails¶

See the Startrails Helper Tool documentation page to help set the Brightness Threshold.

Troubleshooting¶

Warning

The resolution of all images must be identical; if not, only images with the same resolution as the FIRST image are used.

This can happen if the daytime and nighttime Binning settings are not the same, or any day you change the Image Resize and/or Image Crop settings.

If a startrails image isn't being created, make sure the Startrails Generate setting is enabled. If it IS enabled, run:

generateForDay.sh --startrails DATE

replacing DATE with a valid date like 20260710 and check for errors.
If a startrails image is created but not uploaded, make sure the Startrails Upload setting is enabled. If that IS enabled, run:

generateForDay.sh --upload --debug --startrails DATE

and check for errors. If needed, run testUpload.sh to see why the upload fails.