A keogram is an image that gives a quick view of a day's activity. A central vertical column 1 pixel wide is extracted from each image and added to the keogram from left to right.

> Only images that are saved are included in a keogram, so if you don't save your daytime and/or nightime images, they won't be included.

To get the best results, North should be at the top of the image. If it's not, include --rotate DEG in the Keogram Extra Parameters setting in the WebUI, where DEG is the degrees of rotation. That way, using a fisheye lens, you end up with the bottom of the keogram being the southern horizon and the top being the northern horizon.

> Keograms only show what happens at the center of the image and will not display events on the East or West.

## Creating a keogram

You specify whether or not you want a keogram automatically created via the Generate setting in the Keograms sub-section of the WebUI. When enabled, a keogram will be created at the end of night and will contain information for the prior 24 hours.

The easiest way to create and optionally upload a keogram is via the `generateForDay.sh` command. For example, to create and then upload a keogram to any Allsky Website and/or remote server you have for July 10, 2024:

    generateForDay.sh --keogram 20240710
    generateForDay.sh --upload --keogram 20240710

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

#### Advanced users: running the `keogram` program manually

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

Executing the `keogram` program manually is possible, but not very useful. If run manually you need to specify at least the three required arguments.

    Usage:  keogram -d <imagedir> -e <ext> -o <outputfile> [optional arguments]

    Arguments:
    -d | --directory <str> : directory from which to load images (required)
    -e | --extension <str> : image extension to process (required)
    -o | --output-file <str> : name of output file (required)
    -r | --rotate <float> : number of degrees to rotate image, counterclockwise (0)
    -s | --image-size <int>x<int> : only process images of a given size, eg. 1280x960
    -h | --help : display this help message
    -v | --verbose : Increase logging verbosity
    -n | --no-label : Disable hour labels
    -C | --font-color <str> : label font color, in HTML format (#0000ff)
    -L | --font-line <int> : font line thickness (3)
    -N | --font-name <str> : font name (simplex)
    -S | --font-size <float> : font size (2.0)
    -T | --font-type <int> : font line type (1)
    -Q | --max-threads <int> : limit maximum number of processing threads. (use all cpus)
    -q | --nice-level <int> : nice(2) level of processing threads (10)
    -x | --image-expand : expand image to get the proportions of source - avoids tall and narrow images
    -c | --channel-info : show channel infos - mean value of R/G/B
    -f | --fixed-channel-number <int> : define number of channels 0=auto, 1=mono, 3=rgb (0=auto)

    Font name is one of these OpenCV font names:
            Simplex, Plain, Duplex, Complex, Triplex, ComplexSmall, ScriptSimplex, ScriptComplex
    Font Type is an OpenCV line type: 0=antialias, 1=8-connected, 2=4-connected

Example of running the `keogram` program manually:

    cd ~/allsky/bin
    ./keogram -d images/20240710 -e jpg -o images/20240710/keogram/keogram.jpg --rotate 42 --font-size 2

## Troubleshooting

> It is extremely rare that a keogram isn't created.

> 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 keogram isn't being created, make sure the Keogram Generate setting is enabled. If that IS enabled, run:

      generateForDay.sh  --keogram  DATE

  replacing `DATE` with a valid date like `20250710` and check for errors.
- If a keogram is created but not uploaded, make sure the Keogram Upload setting is enabled. If that IS enabled, run:

      generateForDay.sh  --upload  --debug  --keogram  DATE

  and check for errors. If needed, run `testUpload.sh` to see why the upload fails.
- If your keograms are tall and skinny you can have them created so they look like regular images by enabling the Expand setting.