search

dcf21 / star-charter

A command-line tool for producing vector-graphics charts of the night sky in SVG, PDF and PNG formats.
GNU General Public License v3.0
339 stars 29 forks source link
amateur-astronomy astronomy nightsky starchart vector-graphics

readme

StarCharter

StarCharter is a command-line tool for producing vector-graphics charts of the night sky in SVG, PDF and PNG formats. It can also overlay the paths of solar system objects, such as planets and comets, across the sky if the tool ephemerisCompute is also installed.

StarCharter was written to produce all the star charts on the website https://in-the-sky.org, which is maintained by the author.

Supported operating systems

StarCharter is written in C and runs in Linux, MacOS, and other Unix-like operating systems. The installation scripts require python3. StarCharter uses libcairo to produce its graphical output.

The build process requires a minimum of 4GB RAM. Note that Docker Desktop for Mac imposes a default memory limit of 2GB, which needs to be increased to build StarCharter successfully.

License

This code is distributed under the Gnu General Public License. It is (C) Dominic Ford 2015 - 2022.

Set up

Before you start, StarCharter needs to download various data from the internet, including star catalogues, deep sky catalogues, and an image of the Milky Way to use to shade the background of star charts.

This can be done with the shell script setup.sh. The total download size will be around 500 MB.

Docker container

A Dockerfile is provided to build StarCharter. A docker compose script is provided to build a selection of example starcharts:

docker compose build
docker compose run star-charter

This builds some example starcharts, which are written to the directory examples/output. To make other star charts, open a shell within the Docker container as follows:

docker run -it star-charter:v1 /bin/bash

Generating a star chart

Once you have compiled the StarCharter code, you need to write a configuration file to generate each star chart you want, specifying which portion of the sky should be charted, and what labels you want on the chart. There are some examples in the examples directory, and so a good starting point is to generate one of these:

cd examples
../bin/starchart.bin orion.sch

This will generate three star charts in the output directory, in PNG, SVG and PDF formats.

The file orion.sch reads as follows:

DEFAULTS
ra_central=5.5
dec_central=4.0
angular_width=29.0
mag_min=7
width=15.0
aspect=1.41421356
ra_dec_lines=1
constellation_boundaries=1
constellation_sticks=1
coords=ra_dec
projection=gnomonic
star_names=1
star_flamsteed_labels=0
constellation_names=1
plot_galaxy_map=1
plot_equator=0
plot_ecliptic=0
plot_galactic_plane=1
font_size=1.2

CHART
output_filename=output/orion.png

CHART
output_filename=output/orion.svg

CHART
output_filename=output/orion.pdf

CHART
output_filename=output/orion.eps

Settings are arranged in blocks which are headed by the words DEFAULTS or CHART. Settings in a DEFAULTS block do not themselves produce a star chart, but change the default settings which are applied to all subsequent charts. Settings in a CHART relate to a specific chart that is to be rendered, and do not affect any subsequent charts which may be rendered later in the same configuration file.

The file above configures a large number of parameters to produce a star chart of the constellation Orion, and makes these the default settings. It then produces three identical copies of the star chart, in three different graphic formats.

The configuration settings which are recognised are listed below under 'Configuration settings'.

Paths of solar system objects

The draw_ephemeris option in a configuration file can be used to draw the path of a solar system object across the sky. This requires the tool ephemerisCompute to be installed.

The syntax is as follows:

draw_ephemeris = <body>,<jd_start>,<jd_end>

where body is the name of the solar system object to plot, and jd_start and jd_end are the Julian day numbers of the beginning and end of the time period for which the object's path should be plotted.

Recognised object names include any of the following:

Note also the setting ephemeris_autoscale, which overrides the specified celestial coordinates for the centre of the star chart, and the specified angular width, and scales the star chart to automatically show the requested ephemerides.

Configuration settings

The following settings can be included in a StarCharter configuration file:

Author

This code was developed by Dominic Ford https://dcford.org.uk. It is distributed under the Gnu General Public License V3.