这是一个命令行工具,用于以 SVG、PDF 和 PNG 格式生成夜空的向量图形图表。
StarCharter is a versatile command-line tool for producing charts of the
night sky in a wide variety of styles. Planetarium-style charts can be
generated showing the sky and local horizon as seen from any particular
location. Alternatively, charts can be generated in a star-atlas style, in
equatorial or galactic coordinates. A wide range of configuration options are
available to allow charts to be fully customised.
StarCharter can show the positions of solar system objects - planets,
asteroids and comets - automatically retrieving their positions from NASA's
DE4xx series of ephemerides and from orbital elements published online. The
tracks of these objects through the constellations can also be shown over
extended time periods.
Charts can be generated in either PNG (bitmap graphics) format for quick viewing and use online, or in PDF/SVG/EPS (vector graphics) formats for subsequent typesetting or editing in a vector graphics package such as Adobe Illustrator or Inkscape.
StarCharter was originally developed to produce star charts for the website
https://in-the-sky.org, which is maintained by the
author.
You can find a selection of varied examples of the output of StarCharter
here.
This code is distributed under the Gnu General Public License Version 3. It is © Dominic Ford 2015 - 2026.
StarCharter is written in C and runs in Linux, macOS, and most other
Unix-like operating systems. A Docker container is provided to facilitate
running StarCharter in the widest possible range of operating systems. The
installation scripts require Python 3; these scripts download and merge various
astronomical catalogues from online sources. StarCharter uses libcairo to
produce its graphical output.
The build process requires a minimum of 4GB RAM, but once built, the software
requires much less memory. Note that Docker Desktop for MacOS imposes a default
memory limit of 2GB, which needs to be increased to build StarCharter
successfully.
First make a clone of the code in this GitHub repository:
git clone https://github.com/dcf21/star-charter.gitIf you wish to run StarCharter locally (not within a Docker container), then
you must run the shell script setup.sh to download the required astronomical
catalogs from online sources and to compile the software. By default, the
downloaded data includes the DE440 solar system ephemeris, star catalogues,
deep sky catalogues, and an image of the Milky Way used to shade the background
of star charts.
The total download size will be around 1 GB, and it will take around 10-15 minutes to process the downloaded files.
Once you have built StarCharter, you must not change its location within your
file system. During the build process, the absolute path to the downloaded
data files is stored, and the code will be unable to find these data files if
their path changes. If you move the code, you must fully rebuild it:
make clean
./setup.shStarCharter can fetch the positions of the planets from the following
planetary ephemerides, published by NASA JPL:
| Ephemeris | Published | Time period covered | Download size |
|---|---|---|---|
| DE405 | 1997 | AD 1600 to AD 2200 | 184 MB |
| DE430 | 2013 | AD 1550 to AD 2650 | 323 MB |
| DE431 | 2013 | AD 1000 to AD 17000 | 4.6 GB |
| DE440 | 2020 | AD 1550 to AD 2650 | 322 MB |
| DE441 | 2020 | AD 1000 to AD 17000 | 4.6 GB |
By default, only the DE440 planetary ephemeris is downloaded and used, as this is best suited for most purposes.
If you wish to download and use other ephemerides, you need to specify this
when you set up StarCharter with the setup.sh script. You should either
supply the command-line argument --ephemeris xxx, where xxx is the DE
number of the required ephemeris, or use the argument --all-ephemerides to
download all the ephemerides. For example:
./setup.sh --ephemeris 441
./setup.sh --all-ephemeridesThe total download size will range between 1 GB for the default ephemeris, or 12 GB to download all ephemerides.
Note that you must also specify which DE4xx planetary ephemeris to use each
time you run starchart.bin using the --use_de command-line argument
described below (default: DE440).
If you would rather run StarCharter within a Docker container, then a
Dockerfile is provided to build such a container. This automatically
installs all the software's dependencies within the containerised environment
to make the build process as simple as possible. Additionally, a
docker-compose script is provided, which automatically builds a selection of
example star charts.
To build the StarCharter container (this takes 15 minutes):
docker compose buildTo generate a selection of example charts, which are placed in the directory
examples/output:
docker compose run star-charterTo make other star charts, open a shell within the Docker container as follows:
docker run -it star-charter:v10 /bin/bashThe settings for each star chart are specified in a configuration file, where options are specified in the format
=The available options include which portion of the sky should be charted, what labels should be placed on the chart, colours, etc. There is a complete list of all the available configuration options below.
The directory examples within this repository contains numerous example
configuration files; a good starting point is to try generating one of these,
for example:
cd examples
../bin/starchart.bin orion.schThis will generate a set of PNG charts of the constellation Orion in the
output directory, with a variety of labelling schemes.
The example configuration files generally follow the pattern:
DEFAULTS
ra_central=5.5
dec_central=4.0
angular_width=29.0
mag_min=7
width=15.0
....
CHART
... more settings
output_filename=output/demo_1.png
CHART
... more settings
output_filename=output/demo_2.png
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 block 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.
This makes it as easy as possible to render multiple charts with very similar settings - for example, copies of the same star chart in multiple different graphic formats.
A complete list of all the configuration settings which are recognised are listed below under 'Configuration settings'.
The following settings can be included in a StarCharter configuration file:
alt_central - The local altitude of the centre of the plot; degrees. This setting is only used if coords=alt_az.angular_width - The angular width of the star chart on the sky; degrees. Default: 25.arrow - Overlay a line or arrow over the star chart. Each label should be specified in the format ,,,,,,,,,,,, where coordinates should be page or ra_dec. If page is selected, then xpos and ypos are in the range 0-1; if ra_dec is selected then xpos is RA/hours and ypos is Dec/degs. Different coordinate systems can be used for the two ends of the line. head_start and head_end are booleans indicating whether to draw arrow heads on the two ends of the line. The colour components are in the range 0-1. To overlay multiple arrow, specify this setting multiple times within your configuration file.aspect - The aspect ratio of the star chart: i.e. the ratio height/width. Default: 1.414.axis_label - Boolean (0 or 1) indicating whether to write "Right ascension" and "Declination" on the vertical/horizontal axes. Default: 0.axis_ticks_value_only - If 1, axis labels will appear as simply "5h" or "30 deg". If 0, these labels will be preceded by alpha= or delta=az_central - The local azimuth of the centre of the plot; degrees clockwise / eastwards from north. This setting is only used if coords=alt_az.bleed_margin - The bleed margin around the star chart, in cm. A guide line is drawn marking the bleed margin. Default: 0.cardinals - Boolean (0 or 1) indicating whether to write the cardinal points around the edge of alt/az star charts. Default: 1.chart_edge_line_col - Colour to use when marking the edge of the chart. Default: 0,0,0.chart_edge_line_width - Line width to use when marking the edge of the chart. Default: 2.5.constellation_boundaries - Boolean (0 or 1) indicating whether we draw constellation boundaries. Default: 1.constellation_boundary_col - Colour to use when drawing constellation boundariesconstellation_highlight - Optionally, highlight the boundary of one particular constellation, identified by a three-letter abbreviation.constellation_label_col - Colour to use when writing constellation namesconstellation_label_size - Relative font size to use when rendering constellation names. Default: 1.constellation_names - Boolean (0 or 1) indicating whether we label the names of constellationsconstellation_show_below_horizon - Boolean (0 or 1) indicating whether to show constellation stick-figures beneath the horizon. Default: 0.constellation_stick_col - Colour to use when drawing constellation stick figuresconstellation_stick_design - Select which design of constellation stick figures we should draw. Set to either iau (default), rey or simplified. See for more information.constellation_sticks_line_width - Line width to use when drawing constellation stick figures. Default: 1.6.constellation_sticks - Boolean (0 or 1) indicating whether we draw constellation stick figures. Default: 1.constellations_capitalise - Boolean (0 or 1) indicating whether we capitalise the names of constellations. Default: 0.constellations_label_shadow - Boolean (0 or 1) indicating whether to draw a shadow behind the names of the constellations. Default: 1.coords - Select which celestial coordinate system to use when specifying the centre of the plot. Set to ra_dec, galactic or alt_az.copyright_gap_2 - Spacing of the copyright text beneath the plot. Default: 0.copyright_gap - Spacing of the copyright text beneath the plot. Default: 0.copyright - The copyright string to write under the star chartdec_central - The declination of the centre of the plot; degrees. This setting is only used if coords=ra_dec.draw_ephemeris - Definitions of ephemerides to draw. Each definition should take the form of: ,, (see above). To draw multiple ephemerides, specify this setting multiple times within your configuration file.dso_catalogue_file - Source file from which we get DSO catalogue. By default, a catalogue of Messier, NGC and IC objects is used. Only change this setting if you want to show custom deep-sky objects.dso_cluster_col - Colour to use when drawing star clusters. Default: 0.8,0.8,0.25.dso_display_style - Select which style to use for deep sky objects. Set to either coloured or fuzzy. Default: coloured.dso_galaxy_col - Colour to use when drawing galaxies. Default: 0.75,0.15,0.15dso_label_col - Colour to use when writing the labels for deep sky objects. Default: 0,0,0.dso_label_mag_min - Do not label stars fainter than this magnitude limit. Default: unlimited.dso_mag_min - Only show deep-sky objects down to this faintest magnitude. Default: 14.dso_mags - Boolean (0 or 1) indicating whether we label the magnit暂无开放 Issues,或尚未同步最近议题。