A startrails is an image that contains all the images from a night on top of each other in order to show star movement.

> Only nighttime 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 startrails image

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

This will use the settings specified in the Startrails sub-section of the WebUI.

#### 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. If run manually you need to specify at least all the required arguments.

    Usage: startrails [-v] -d <dir> -e <ext> [-b <brightness>] [-o <output>] [-S] [-s <width>x<height>]

    Arguments:
    -h : display this help, then exit
    -v : increase log verbosity
    -S : print image directory statistics without producing image.
    -s <int>x<int> : restrict processed images to this size
    -d <str> : directory from which to read images (required)
    -e <str> : filter images to just this extension (required)
    -o <str> : output image filename
    -b <float> : ranges from 0.0 (black) to 1.0 (white).
            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 log file.

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:

1. Run `allsky-config get_brightness_info` to see what your brightness values are.
2. If there is no data yet a message will appear with a possible reason, otherwise the output will look like:

       Date                   Minimum   Maximum   Mean      Median    Images used   Not used
       -------------------------------------------------------------------------------------
       2025-01-17  06:20:45   0.084     0.146     0.103     0.105     250           3
       2025-01-18  06:16:18   0.045     0.135     0.102     0.106     247           6
       -------------------------------------------------------------------------------------
       Total average          0.065     0.140     0.103     0.106     497           9

   > 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.

3. Set the Brightness Threshold to the Maximum, or slightly below it. If you have a `Total average`, use its Maximum.

You'll now create a startrails and if needed, change Brightness Threshold, then create another startrails, change the setting, etc.

1. To make startrails generation MUCH faster, do it using a small number of images.
2. Create a temporary directory to hold some nighttime images: `mkdir ~/allsky/images/test`.
3. `cd ~/allsky/images/DATE`, replacing `DATE` with the date of a non-working startrails.
4. Using the timestamp of each image, move a few hours of nighttime images to the ~/allsky/images/test directory:
   - If you are running SAMBA (`allsky-config samba`) you can view the files from your PC or Mac and then select some files with the mouse and drag to the test directory.
   - If you are not running SAMBA and you are logged into the Pi desktop, open a "File Manager" window on the Pi and drag/drop the files.
   - If neither of the above work for you, you'll need to use the `mv` command to move the files. Using the `*` wildcard in the file names will allow you to move multiple files at a time.
     For example: `mv 2025071001* ../test` to move all the images taken from 1:00 AM to 1:59 AM.
5. Run `generateForDay.sh --startrails test` to create a startrails file in the test directory. Look at the image using the Images page in the WebUI. Also look at the `Images used` and `Not used` columns of the output.
6. As needed, adjust Brightness Threshold and re-run `generateForDay.sh`.
7. When done, move all the images from the allsky/images/test directory back to allsky/images/DATE.
8. Remove the temporary directory: `rmdir ~/allsky/images/test`.
9. Now, create the final startrails:
   - `generateForDay.sh --startrails DATE`
   - If you want to upload the file you just created, see the note generated by `generateForDay.sh`.

## Troubleshooting

> It's extremely rare that a startrails image isn't created at all. It's much more common that an image is created but none of the stars have trails. If none of the stars have trails, see the Startrails settings section above.

> 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 `20250710` 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.