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.

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.

You can execute the keogram program manually, but will need to specify at least all the 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

If a keogram isn't being created, make sure the Generate setting is enabled. If that IS enabled, run:

generateForDay.sh --keogram DATE

and check for errors.

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

If a keogram isn't being uploaded, make sure the 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.