weewx-skymap-almanac

Sky map, Moon with phase and tilt, and astronomical diagrams for WeeWX

Contents

• Prerequisites
• Installation instructions
• Configuration instructions
• Sky map
• Zodiac map
• Moon with moon phase
• Analemma
• Libration
• Equation of time
• Diagram of visibility
• Styling
  • Dark mode of your web site
  • General font setting
  • Special settings
• Changing visibility of elements by JavaScript
• Creating pure SVG vector graphics files
• Localization
• How to check whether this extension is available?
• Credits
• Links

Prerequisites

WeeWX from version 5.3 on and weewx-skyfield-almanac

Note

You have to install weewx-skyfield-almanac first before installing this extension.

Note

You need the actual version of weewx-skyfield-almanac together with this extension.

Installation instructions

1. download

   wget -O weewx-skymap-almanac.zip https://github.com/roe-dl/weewx-skymap-almanac/archive/master.zip

2. run the installer

   WeeWX from version 5.3 on and WeeWX packet installation

   sudo weectl extension install weewx-skymap-almanac.zip

   WeeWX from version 5.3 on and WeeWX pip installation into an virtual environment

   source ~/weewx-venv/bin/activate
   weectl extension install weewx-skymap-almanac.zip

3. restart weewx

   for SysVinit systems:

   sudo /etc/init.d/weewx stop
   sudo /etc/init.d/weewx start

   for systemd systems:

   sudo systemctl stop weewx
   sudo systemctl start weewx

Configuration instructions

There is no need to configure anything, but there are some tuning options available if you have special requirements.

Note

If you are new to this extension, please, do NOT change the configuration at the beginning. The installation sets reasonable values to all configuration keys to immediately include the new tags into your skin.

[Almanac]
    [[Skymap]]
        # use this almanac
        enable = true
        # list of heavenly bodies to include in the map
        bodies = ...
        # list of earth satellites to include in the map
        earth_satellites = ...
        # maximum star magnitude to include in the map
        max_magnitude = 6.0
        # flag whether to include stars in the map
        show_stars = true
        # flag whether to include the timestamp
        show_timestamp = true
        # flag whether to include the location
        show_location = true
        # flag whether to show the ecliptic as a dotted line
        show_ecliptic = true
        # flag whether to show the constellation lines between the stars
        show_constellations = true
        # optional list of localization sources
        additional_localization_sources = internal, Seasons
        # format options
        [[[Formats]]]
            stars = mag, '#ff0'
            object_name = size, color, ...

• enable: Enable this almanac extension.
• bodies: List of heavenly bodies to include in the map. Optional. Default the sun, the moon, and the well-known planets. This can include all objects available in BSP files.
• earth_satellites: List of earth satellites to include in the map. Optional. Default no satellites. The ID to use here contains of the file name of the satellite data file (without file name extension) and the catalog number of the satellite, connected by an underscore.
• max_magnitude: Maximum star magnitude to include in the map. Optional. Default is 6.0. This is, how you would see the sky in a clear night in the middle of nowhere. Try 4.0 if that looks more the way you know the sky in the night to be. Please note, the larger the magnitude, the fainter the star.
• star_tooltip_max_magnitude: Stars get a tooltip if their magnitude is less than this value. Optional. Default is 2.5.
• show_stars: Flag whether to include stars in the map. Optional. Default True.
• show_timestamp: Flag whether to include the timestamp. Optional. Default True.
• show_location: Flag whether to include the location. Optional. Default True.
• show_ecliptic: Flag whether to show the ecliptic as a dotted line. Optional. Default True.
• show_constellations: Flag whether to show the constellation lines between the stars. Optional. Default True. Uses the constellationship.fab file of Stellarium.
• show_path_of_sun: Flag whether to show the path of the Sun during the day. Optional. Default False.
• show_path_of_moon: Flag whether to show the path of the Moon during the day. Optional. Default False.
• moon_colors: Colors for moon_symbol. Optional. Default '#bbb4ac19','#ffecd5','#da6d5e'. The first value is the color of the dark side, the second color that of the sunlit side, the third the axis color. For the dark side an opacity value can be provided. You can set an URL pointing to a Moon picture for the second color like '#bbb4ac19','url(moonpicture.svg)','#da6d5e' to let the sunlit side look like the real Moon. Replace moonpicture.svg by the path to the file, which can be SVG, PNG, or JPEG. Instead of referencing an URL you can also include an SVG file. Use a color list like ``'#bbb4ac19','include(/path/to/moonpicture.svg)','#da6d5e'` for that.
• analemma_colors: Colors for analemma. Optional. Default 'currentColor','#808080','#7cb5ec','#f7a35c'
• additional_localization_sources: Optional list of additional sources of localized words. In general you do not need this key. If present, the listed sources are read in order. Default internal, Seasons.
• [[[Formats]]]: Format options. Optional. There are reasonable defaults. So you do not need this section at all. But if you want to set up something special you can do it here. Each entry contains an object name and a list of options. For example the line stars = mag, "#ff0" says that the stars are to be drawn with a diameter according to their magnitude and a color of yellow. This is also the default if no option is specified. A line mars_barycenter = 0.85, "#ff8f5e" would draw the planet Mars with a radius of 0.85 and a reddish color. This is the default, too. For earth satellites a third parameter is possible describing the shape of the representation of the object. For example it can be round, triangle, square, or rhombus.

All the configuration options can also be used as parameters to the attributes described below.

Example [Almanac] configuration section in weewx.conf:

[Almanac]
    [[Skyfield]]
        enable = true
        ephemeris = de440.bsp
        use_builtin_timescale = false
        timescale_url = https://datacenter.iers.org/products/eop/rapid/standard/finals2000A.all, ftps://gdc.cddis.eosdis.nasa.gov/products/iers/finals.all
        "#log_ftp" = false
        update_interval = 31557600
        enable_live_data = true
        disable_pyephem = false
        [[[EarthSatellites]]]
            stations.tle = https://celestrak.org/NORAD/elements/gp.php?GROUP=stations&FORMAT=tle
            gps.tle = https://celestrak.org/NORAD/elements/gp.php?GROUP=gps-ops&FORMAT=tle
            weather.tle = https://celestrak.org/NORAD/elements/gp.php?GROUP=weather&FORMAT=tle
    [[Skymap]]
        enable = true
        earth_satellites = weather_40732, weather_38552, weather_28912, stations_25544, gps_24876, gps_26360, gps_26407, gps_27663, gps_28190, gps_28474, gps_28874, gps_29486, gps_29601, gps_32260, gps_32384, gps_32711, gps_35752, gps_36585
        [[[Formats]]]
            gps_* = 3, "#10A010", round
            stations_61447 = 3, "#A010A0", round
            weather_* = 1.5, "#00deff", square

Please especially adjust the [[[EarthSatellites]]] section and depending earth_satellites key to your needs. If you don't want to show Earth satellites you can remove that section and that key.

Sky map

Usage

Add $almanac.skymap to your skin.

The map shows the sky as you would see it if you were lying on the ground, your legs to the south, and looking upwards. The size of the heavenly bodies on the map is not according to scale.

Parameters

You can change the size of the map or other properties by setting parameters like $almanac.skymap(width=1200). All the options that are defined for the configuration file can also be used as parameters. Additionally there are the following parameters defined to adjust the layout. All of them are optional:

• width: Width and height of the map. Default 800. Possible values are numbers with or without percent sign or auto.
• max_width: Maximum width and height of the map. Default not specified. Use it together with width='auto'.
• fromoutside: If set to True show the celestial sphere from the outside. Default is to show it from the inside as you see it if you lay on the ground, legs to the south.
• location: Location as text (for example the city name). Appears in the lower left corner of the sky map if provided instead of pure geographic coordinates. An empty string switches it off.
• credits: Credits text in the lower right corner of the sky map. Default is the text of the option location in weewx.conf together with the copyright sign.
• x and y: In case you want to include the sky map into another SVG image, you can set position by the x and y parameters.
• html_class: set an HTML class for styling
• id: assign an HTML ID to the SVG tag
• horizon: list of altitude values in degrees that represent the visibile horizon, from north to east to south to west and back to north, in equidistant azimuth steps. If you look for a location within the European Union, you can get a rough estimate of the horizon for free from the European Commission at PVGIS.
  
  This example map shows the sky over the railway station of Rittersgrün (which is a museum about Saxon railway history now) with the visible horizon in that narrow mountain valley. You see that the sun disappears behind the mountains there shortly after noon at this time of year.
• night_color: background color at night, tuple of RGB values
• day_color: background color at light day, tuple of RGB values
• horizon_night_color: horizon area color at night, tuple of RGB values
• horizon_day_color: horizon area at light day, tuple of RGB values

Time

The sky map image contains different timestamps:

• Solar time: In the upper left corner you find the apparent solar time. That is the time a sundial would show. It represents the position of the sun in the sky.
• Sidereal time: In the upper right corner you find the apparent sidereal time.
• Civil time: Civil time you find in the lower right corner together with the date.

Zodiac map

This map shows the astronomical zodiac, not the astrological one. It shows the actual position of the Sun, the Moon, and the planets before the background of the stars.

The dotted magenta line is the ecliptic. All the bodies of the solar system are found near it. Magenta lines mark the 12 zodiac constellations. Their names are above the map. In astronomy, the solar system bodies pass a 13th constellation, Ophiuchus (Oph), which is traditionally not considered part of the zodiac. You see its yellow line cross the ecliptic near Scorpion.

The map is based on equatorial coordinates and covers an area of +-30° around the celestial equator. The background color marks, which part of the map is actually above and below the horizon at your location. Blue background is above, brown background is below it.

If you position the mouse above one of the heavenly bodies, a tooltip window with additional information is displayed.

Usage

Add $almanac.zodiacmap to your skin. It is recommended to enlarge the size by setting width like $almanac.zodiacmap(width=1600).

Parameters

The parameters are the same as those of the sky map, but there is one additional paremeter:

• show_visibility: Whether to color the map background according to the visibility of that area at the current time and location. Default is on.

The zodiac in history

The March equinox slowly moves through the zodiac within about 25800 years. So in history you see the Sun and the other heavenly bodies in other constellations at same time of year. If you loaded an ephemeris file that covers a long range of time you can display the situation in ancient times by setting almanac_time to a timestamp far in history. With the standard ephemeris file you can go back until 1551.

Moon with moon phase

Add $almanac.moon_symbol to your skin.

You can change the size of the symbol by setting the parameter width like $almanac.moon_symbol(width=200). You can also set a maximum size by setting the parameter max_width like $almanac.moon_symbol(width='auto',max_width=200).

To switch off moon tilt, use $almanac.moon_symbol(with_tilt=False).

To hide the line of the Moon axis, use show_axis=False.

In case you want to include the moon symbol into another SVG image, you can set the position by using the parameters x and y.

For styling you can set an HTML class using the html_class parameter and assign an ID using the id parameter.

Pictoral representation of the Moon

If you want to use a Moon picture for the sunlit side you can set an URL in the moon_colors configuration option or the colors parameter. The value could be ['#bbb4ac19','url(moonpicture.svg)','#da6d5e'], where moonpicture.svg ist to be replaced by the name or the URL of the file, respectively. Omit the brackets in the configuration file.

You can use every full-size picture of the full Moon. Besides SVG, PNG and JPEG are possible. An example of such an image is the moon dan gerhards 01 or full moon dan gerhards 01. Make sure the image shows the Moon with her axis oriented vertically.

You don't always see exactly the same part of the Moon's surface due to libration. Therefore you can provide a PHP script for the picture that observes the libration_latitude and libration_longitude parameters provided when fetching the URL and returns a picture according to that libration value.

In case you experience displaying errors and use an SVG image, you can alternatively include the file instead of referencing it. Use ['#bbb4ac19','include(/path/to/moonpicture.svg)','#da6d5e'] for the color then. If you have different files for different libration states you can use libration_latitude and libration_longitude as place holders in the file name, for example /path/to/moonpicture_{libration_latitude:.1f}_{libration_longitude:.1f}.svg.

Analemma

Usage

Add $almanac.analemma to your skin.

The analemma is calculated for the year and the time of day $almanac is bound to. You can change it by setting almanac_time.

Parameters

All the options that are defined for the configuration file can also be used as parameters. Additionally there are the following parameters defined to adjust the layout:

• width: Width of the diagram. Default 280.
• height: Height of the diagram. Default 300.
• location: Location as text (for example the city name). Appears in the caption of the analemma. An empty string switches it off.
• tz: Time in the caption of the analemma. Possible values are:
  • LMT: Local Mean Time. This differs from solar time by the equation of time. Often an analemma is provided for 12:00:00 Local Mean Time.
  • UTC: UTC
  • civil: The local time as used by WeeWX. This is the default.
• caption: Diagram caption. Default is the localized word for Analemma.
• y_axis_label: Y axis label. Default is the localized word for Altitude.
• x_axis_label: X axis label. Default is the localized word for Azimuth.
• lmt_name: In case of tz='LMT' how to mark Local Mean Time. Default is the localized name or abbrevation of it.
• html_class: set an HTML class for styling
• id: assign an HTML ID to the SVG tag

This is the analemma at the Royal Observatory Greenwich at high noon mean time:

Libration

Usage

$almanac.libration_diagram(context='...', ...)

Parameters

• width: Width of the diagram. Default 280.
• height: Height of the diagram. Default 300.
• location: Location as text (for example the city name). Appears in the caption of the analemma. An empty string switches it off.
• context: timespan and time of day
  • day: today
  • moonmonth hourly: from new moon to next new moon, calculated hourly
  • month hourly: actual month, calculated hourly
  • month transits: actual month, calculated at the time of the Moon transits
  • year: actual year, calculated at the time of the Moon transits
• caption: Diagram caption. Default is the localized word for Libration.
• y_axis_label: Y axis label. Default is the localized word for Selenographic latitude.
• x_axis_label: X axis label. Default is the localized word for Selenographic longitude.
• html_class: set am HTML class for styling
• id: assign an HTML ID to the SVG tag

Equation of Time

The equation of time describes the difference between the apparent solar time and the local mean time.

Note

The sign of the values changed in history. Originally it was the value to add to a sundial reading to get the mean time. Now the difference between the apparent solar time and the mean solar time is given.

Usage

$almanac.eot_diagram or with parameters $almanac.eot_diagram(...)

Parameters

• width: Width of the diagram
• height: Height of the diagram
• noon: If True calculate the diagram for high noon local mean time. Optional. This the default. If set to False the actual time is used that $almanac is bound to. The diagram looks the same, but the y scaling differs.
• show_today: If True mark the actual day (the day $almanac is bound to). Optional. This is the default
• show_lmt: If True mark the average of the solar time. Optional. This is the default
• show_legend: If True show a legend under the diagram. Optional. Default is False for the equation of time diagram and True for the rise-transit-set diagram
• y_axis: Which unit is used for the y axis and how it is labeled:
  • lat: Local apparent solar time at the given mean time
  • lmt: Local mean solar time at the given apparent solar time
  • solar-mean: The difference between apparent solar time and mean solar time (This is the actual way to present it.)
  • mean-solar: The difference between mean solar time and and apparent solar time (This is the historical way to present it.)
  • time of day: Instead of the equation of time draw lines of sunrise, transit, and sunset.
• x_label_format: Format of the x axis labels. Default is the date format setting of the operating system without year (%x). Possible alternatives are for example %d.%m., %m/%d, %m, or %b.
• location: String to use as location in the diagram caption. Default is the station location as specified in weewx.conf.
• html_class: set am HTML class for styling
• id: assign an HTML ID to the SVG tag

Diagram of visibility

This diagram shows rising, transit, and setting time of a heavenly body. All bodies loaded into the weewx-skyfield-almanac extension are available.

Usage

$almanac.heavenly_body.year_diagram or $almanac.heavenly_body.year_diagram(...)

Parameters

• width: Width of the diagram
• height: Height of the diagram
• show_today: If True mark the actual day (the day $almanac is bound to). Optional. This is the default
• show_legend: If True show a legend under the diagram. Optional. Default is True if not specified.
• location: String to use as location in the diagram caption. Default is the station location as specified in weewx.conf.
• html_class: set am HTML class for styling
• id: assign an HTML ID to the SVG tag

Replace heavenly_body by the name of the body. In case of outer planets add _barycenter.

Styling

Dark mode of your web site

If you insert the tags into your web page template as described above dark mode is observed properly. The background and the text around the map and in the diagram is colored as you configured it by CSS for your website in general.

The sky color does not depend on light or dark mode but on the time of day. It is dark at night and light at day, and in dawn it is in between.

But if you save the images created by the tags to separate files and include them using the <img> tag (what we do NOT recommend), then you will have to set up colors appropriately by the colors parameter or configuration option.

General font setting

To set up fonts the web page should include a CSS file or the <style> tag in the <head> section. Often you will have a general font definition there, that applies to the texts of the images from this extension, too. So in most cases you have nothing to do to set up the font used, but if not, you can use the following declarations:

CSS:

body {
    font-family: sans-serif;
    font-weight: normal;
}

Style within the template:

<style>
    body {
        font-family: sans-serif;
        font-weight: normal;
    }
</style>

If you want to use another font for the sky map than generally on your page, replace body by svg.

Special settings

All the tags of this extension can have a html_class parameter which adds an HTML class or a list of such classes to the image. You can use that class to set styling options within in CSS files or <style> sections.

For example, if you use the parameter html_class="myskymap" like in $almanac.skymap(html_class="myskymap"), then you could put into your CSS file:

.myskymap {
    font-family: sans-serif;
    font-weight: normal;
}

Changing visibility of elements by JavaScript

If you want your users to be able to switch on and off some parts of the map, for example the constellation lines, you can do so by JavaScript. The elements have IDs for that.

To switch off the constellations lines the script looks like this:

let el = document.getElementById('constellations');
if (el)
  {
    el.style.display = "none";
  }

To switch on the constellation lines the script looks like this:

<script>
let el = document.getElementById('constellations');
if (el)
  {
    el.style.removeProperty("display");
  }
</script>

You cannot only switch on and off elements, but also change the color to highlight it. This script highlights Polaris by enlarging its diameter and changing its color and reverts to the original values after a short period of time:

let el = document.getElementById('HIP11767');
if (el)
  {
    let r = el.getAttribute("r");
    let f = el.getAttribute("fill");
    el.setAttribute("r","3");
    el.setAttribute("fill","#00f");
    setTimeout(() => {
        el.setAttribute("r",r);
        el.setAttribute("fill",f);
    }, 1000);
  }

If you assign that script to a button, the user can easily find the star on the map by pressing the button.

The following IDs are defined:

• altitude_scale: altitude scale within the sky area
• circle_of_right_ascension: circle of right ascension and border of the circumpolar area
• circle_of_ecliptic: dotted line of the circle of the ecliptic
• constellations: constellation lines
• constellation_+constellation abbreviation: the lines of a specific constellation, named by its international abbreviation
• planet name: a planet on the map (add _barycenter for the outer planets)
• Earth satellite ID: an Earth satellite
• HIP+Hipparcos catalogue number: a single star on the map

Creating pure SVG vector graphics files

The WeeWX Cheetahgenerator template to create an SVG vector graphics file looks like that:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
$almanac.venus.year_diagram

Replace the $almanac tag by the one you need.

If you need PNG files, you may want to have a look at the weewx-svg2png extension.

Localization

To adapt skins to local languages, WeeWX uses language files. These files include an [Almanac] section that contains at least one key called moon_phases. This WeeWX almanac extension also uses the value of that key to name the moon phases.

The same applies to compass directions which come from directions in section [Units], sub-section [[Ordinates]].

If there are no language files in your skin, look into skin.conf for those sections and keys. If even there they are missing, they could be found within weewx.conf in section StdReport.

The maps and diagrams provided by this extension use additional keys. You have to put them into the language files of your skin in order to get localized texts. Put them in sub-section [[Astronomcial]] of section [Texts].

• First point of Aries
• Distance: Label for the distance of heavenly bodies
• Magnitude: Label for the magnitude of stars
• In constellation: Label for the constellation the heavenly body is in.
• ecliptical: Label for ecliptic coordinates
• equatorial: Label for equatorial coordinates
• Phase angle: Label for the phase angle of Mercury and Venus
• Apparent size: Label for the apparent size of a heavenly body
• Position: Label for the position of a satellite
• Data source: Label for the data source
• Moon tilt: Label for the moon tilt
• Libration: Label for the libration coordinates
• Analemma: The caption of the analemma diagram
• Selenographic latitude: Axis description
• Selenographic longitude: Axis description
• Equation of Time: The caption of the equation of time diagram
• {tLMT} {LMT} ({tCivil}) ⇒ {LAT}: Sub-caption of the equation of time diagram
• {tLAT} {LAT} ⇒ {LMT}: Another Sub-caption of the equation of time diagram

Some labels are pre-defined in most skins:

• Sunrise, Sunset, Rise, Set, Transit: Names of the lines in the visibility diagram
• Altitude: Label for the astronomical altitude
• Azimuth: Label for azimuth
• Declination, Right ascension: Names of the coordinates of the equatorial coordinate system
• Moon Phase, Phase: Label for the phase of the Moon

The names of heavenly bodies and phases reside in section [Almanac]:

• moon_phases: Phases of the Moon, generally pre-defined in all skins
• venus_phases: Phases of Venus
• mercury_phases: Phases of Mercury
• planet_names: List of the names of the planets of the solar system, sorted by their distance to the Sun, including Earth and Pluto.
• sun: local name of the Sun
• moon: local name of the Moon

Put the names of the timezones in section [Almanac], sub-section [[TZ]]:

• LAT: localized abbrevation of the local apparent solar time
• name(LAT): localized name of the local apparent solar time
• name(LAST): localized name of the local apparent sidereal time
• name(LMT): localized name of the local mean solar time
• CET: localized abbrevation of the Central European Time (Replace by your timezone)
• CEST: localized abbreation of the Central European Summer Time (Replace by your timezone)
• name(CET): localized name of the Central European Time (Replace by your timezone)

Put the names of the constellations in section [Almanac], sub-section [[Constellations]].

How to check whether this extension is available?

If you write a skin, you may want to know whether the user installed and enabled this extension or not. You can do so this way:

#import weewx.almanac
## get a list of the names of the installed almanac extensions
#set $almanac_names = [$alm.__class__.__name__ for $alm in $weewx.almanac.almanacs]
## check if the Skymap almanac extension is available
#set $skymap_almanac_available = 'SkymapAlmanacType' in $almanac_names and $almanac.hasExtras

Then you include and exclude code by using #if $skymap_almanac_available.

Please note that $varExists() does not work with attributes that have one element level after $almanac only.

Credits

• Tom Keffer et al. (WeeWX)
• Brandon Rhodes (Skyfield)
• Fabien Chéreau (Stellarium)

Links

• WeeWX
• weewx-skyfield-almanac
• List of brightest stars
• Liste der hellsten Sterne
• Andrea K. Myers-Beaghton et al.: The moon tilt illusion
• Karlheinz Schott (†): "Falsche" Mondneigung - Wohin zeigt die Mondsichel? (german)
• Skymap example page
• Moon symbol example page
• Search subdirectory lang for additional translation files (2026-02-28)