Documentation?

[gzotti]

The images here look impressive, and the website looks great. However I fail to find a detailed description of the options and how a config file may be formatted in case one wants to create some map pipeline for recurring applications like a club newsletter or observing workshops. The --help alone is a bit short on details. A few practical issues found within minutes of mapmaking (PDF). The tool looks powerful, probably these things can be made already, but I don't see it.

So far I have found out the color format. A specified background color should probably be clipped to the map area and also exclude legend areas. Or specify both, background (for paper/image when people switch to white stars on black) and map-background (for pastel atlas-kind images)?

--show-enhanced-milky-way seems not to show anything. specifying --milky-way-color does not help. --show-simple-milky-way just applies a gray background to the map area (in a 120 degree map).

Should an IAU constellation name like UMa (case insensitive?) make a finder chart for that constellation? It draws something centered along the equator, south of Taurus, but I see no relation to Uma.

Issue #5 indicates some projections may be available. I see no command-line option mentioned.

The --caption option seems not to work. Does it write into the (clipped, hidden) border?

Coordinate numbers are clipped along the upper border

How would I make a "map for tonight"? (I.e., horizontal with timestamp, fisheye or stereographic, 180° FoV) Is there a way to include a horizon polygon?

Is the equatorial grid for J2000 or some epoch? I see an epoch mentioned, pointing to 2016. How do I specify epoch or at least "today"?

[skybber]

Thanks for the detailed report — you’re right: the CLI is currently under-documented and --help is too short without examples.

On your specific points:

• --show-enhanced-milky-way: is fixed now.
• caption + coordinate numbers should be fixed, it's not difficult
• horizontal (alt/az) + time handling, are missing now in fchart3 cmdline utility
• "Map for tonight" / horizon / epoch “today”: same root cause — requires time+geo in the CLI.
• Constellation target like UMa, projection selection - there isn't support in constellation caption in the skymapengine now, but it is not hard to do.
• fisheye projection is missing in skymap engine
• Planets: currently computed outside the engine and injected as ready-made positions. It would be better to integrate planet ephemerides into fchart3 itself.

[gzotti]

Thanks, yes, Milky Way shades now work and look really good. --show-simple-milky-way is still broken and just adds a gray background to the map area. (I know it can be tricky, did some Postscript star maps.) The --show-dso-legend and --show-coords-legend are broken, and -capt does still nothing.

Likewise, the format of the config file: I have finally found default. Is there a complete list of keys? I have tried configuring show_enhanced_milky_way=True. This does nothing, I still have to give this on the command line. Output-dir, fieldsize, limit-star, limit-dso, and actually all CLI options should be configurable in the config file.

Planet positions could be read in from an auxiliary file with some simple syntax: ObjName/RA/DEC/symbol, positions created with whatever means the user may have. (I think there is some pyephem?)

We (Stellarium) have changed our star catalog a year ago. Do you read the new format, or are these the old files (up to version 24.4)?
Likewise, our skyculture format was changed in V25.1. When reading a constellation lineset, this is now a JSON and may be easier to parse, consider making charts for Chinese or other non-standard constellations.

[skybber]

--show-simple-milky-way is fixed now; same for the DSO+coord legend (both are transparent now — that should be fixed as well).

As for the configuration: the loader has been updated, and I’ve updated default.conf. All supported parameters are included now.

Planet positions could also be loaded from Skyfield — I’ve had great experience with it.

The star catalogue was updated this year to the Gaia catalogue (the early-2025 Stellarium version).

Sky culture could be dynamic, as you suggested — like it is in Stellarium now.

Are you considering using fchart3 as the printing engine in Stellarium? That could be a good motivation to improve the fchart3 API. I’m mostly using fchart3 as the drawing backend for online maps (www.czsky.eu) now.

[gzotti]

I had not considered connecting the projects, but tried this just as member of a few amateur clubs which may want to create handouts for the public (we would of course add a line like "created with fchart3, URL..."), and editor of the Astronomical Almanach for Austria (free on Zenodo). My own self-computing Postscript maps include the planets, BSC stars and Messier objects, but are geared towards naked-eye use. For "deeper" maps I loosely investigate options for star maps, and fcharts3 looks like a system worth a closer look. However, for the Almanach I won't create Messier charts, but specialized things like asteroid trails (opposition loops) or maybe meteor radiants. I saw --add-cross, this could probably be expanded. Stellarium or yes, Skyfield (I remember having seen the name. Have not really tried it.), could be used to create input data. But I have not yet looked into your code, Stellarium keeps me busy, and holidays are scarce, so I am not sure whether I find enough time for this Xth side project...

But a loose connection may be useful, i.e., using current star catalog and stepping up to the skyculture format and dynamically load whatever skyculture/index.json is available on the local system from the current Stellarium dir, either git source or installed program dir.

From Stellarium, maybe a script can be configured that triggers rendering an approximate view to PDF. Not sure how to call an external process from a script, it may be deliberately forbidden. We have a dormant "printsky" plugin that needs to be completely redefined. However paper is portrait oriented, screens landscape, Stellarium has multiple projections, etc., so a few more settings will have to be configured. Currently I have no time for this, though.

[skybber]

I've added following new parameters:

• --show-solar-system - planets + moons (skyfield is required)
• --time , --obs-longitude, --obs-latitude
• --cord-system - (equatorial / horizontal)

[gzotti]

Great! I have cloned the project first to WSL, but did not want to install a large Python IDE. Later I transferred to my WIndows space and used pycharm to get a clearer view. I have added entries output_dir, limit_stars, limit_deepsky and fieldsize to the config file, and (to fight the confusing -- vs. - args - is there a reason for not having long options everywhere?) just added aliases --limit-star, --limit-dso, --width (the short option could become -w), --height (short could become -h), --fieldsize (short could become -fov or even -vfov for vertical field of view: Or is it the larger dimension? did not investigate this.) and restored --caption with correct vertical placement. It's not the cleanest solution though., as I may abuse some engine configuration object with fchart3 program settings. (Missing some architectural design and what-goes-where documentation... Also Python itself invites to document more. Writing the idea behind a function really makes life considerably easier for newcomers.) I also fixed the allmessier target run and added some further "fresh install" notes for newbies. Are you interested in a pull request?

A polygonal horizon compatible with Cartes du Ciel (and thus, by definition, Stellarium's polygonal horizon) would be helpful. The best way would be actually pointing at some Stellarium/landscapes/landscape_name directory (entry of course configurable in config file to avoid typing each time) and read landscape.ini for location and polygonal_horizon_list (and adjust by polygonal_angle_rotatez). See Stellarium User Guide 7.1.2. Users could utilize Peakfinder or HeyWhatsThat web services to create their horizon polygons. If no polygon is found, location can still be taken from there and a zero-altitude horizon plotted (cutting out stars below horizon). What about refraction/extinction in maps in horizontal coordinate system?

I have still not found any date dependent code although I am slowly approaching the rotation matrix area. Are the maps and coordinates in J2000 or some other epoch? (I think I have seen it once, some JD pointing to around 2016?) Can you give information about the applicable date range? Would the maps be correct for, say, 3500BC (Precession, proper motion, DeltaT esp. for lunar positions or eclipse prediction)? Are tiny effects: nutation, aberration, location of binary components included in very close-up maps?

Concerning object selection: Addressing Bayer/Flamsteed names like "Alpha Her" (or 3-letter abbreviations like "Ups And"), "51 Peg" or even "HIP123456" would be great, as well as just the 88 IAU constellation name shorts. Also some information about which "further catalogs" are available, LBN, Sh2, Barnard?

[skybber]

It would be great, if you contribute to the project, please create PR.

[skybber]

option --stellarium-landscape is added as you suggested.

I’ve neglected the fchart3 command line for a long time, so it's not in great shape, as you've discovered. Switches should be definitely refactored and use short variants like -fov etc. for the more frequent ones. Furthermore, the mechanism for overriding config values with command line parameters needs to be properly implemented. I see it’s currently just printing the values from the switches. It would be ideal to have a TODO file listing what needs to be done so we can check things off one by one.

[gzotti]

I saw your new options (GREAT!), however the skyfield must be added to the requirements when setting up the venv.

Selecting e.g. "Jupiter" as object apparently fails. Ah no, have to add --show-solar-system, OK. Huh, this downloads the huge bsp files... Hmm,then does something but has Jupiter not in center.

show_horizontal_grid then also fails with a None type error.

Also, how would I create a "map of the Western sky (i.e., azimuth 270°) for tonight 22:00h" with horizontal and equatorial gridlines, probably 90° FoV centered at 45° altitude. 6-8 of such pages could provide a binocular guide for an evening. IMHO date/time and location should be noted in some small-font legend.

A propos small-font: The grid labels are much bigger now, loo large IMHO. Where can I influence that?

My path of reading config into the engine config object may not be "clean", it just worked. There must in any case be a clear sequence of most settings: program default, your default.conf, user config file, and CLI options as last.

I can add a TODO.md with Github-style checkboxes and my wishlist. Not sure if that works... Seriously, most of my wishes may be reachable, but need code checks instead of reading application notes.

I am not so familiar with Python (was looking mostly elsewhere for the last 15 years), but re-started last year. Today I have read the "egg" stuff is deprecated. Also, string formatting looks very old. Should I keep the old style when I add something, or is Python3.6+ style (f-string) welcome?

[skybber]

Fixes:

• --show-horizontal-grid
• size of grid label is configurable now

New support for horizontal position as source:

fchart3 --coord-system horizontal --obs-latitude 50.0755 --obs-longitude 14.4378 --time "2026-01-04T22:00:00+01:00" --show-horizontal-grid --fieldsize 120 -limstar 7 -limdso 7 "h:270,45,Western sky 22:00"

Otherwise, I'm not expert on Python, I'm mostly doing in Java and C++, but I love Python simplicity. If you find some old school code, please rewrite it. fchart3 command line was originally designed in Python 2.6.

Also please add your check list to TODO.md, THANKS for help!

[gzotti]

Horizontal seems to work now, but the azimuth 360-h now. Specifying 270 plots eastern sky etc. :-)

[gzotti]

This is going very well already. I just added landscape-oriented paper option. 4 sheets of paper can make nice directional evening maps including some artificial horizon from Peakfinder (in Stellarium format) to hand around without distracting screen lights. (A dim red flashlight still rules outdoors...) Most desired would be planet and star name targets for bino target maps, and asteroid/comet trails.

[skybber]

Great! I've added search for planets,moons and stars today (alpha Ori must be used now instead of Betelgeuze since star common name is missing in BSC, that is used in fchart now).

[gzotti]

Excellent! I can live with "Alp Ori". I have seen the BSC/HIP mix but have not investigated deeper which data comes from where (and why). It would be nice to just have the star names, at some point, from Stellarium 25.1+ directly, the skycultures include both, their own culture-dependent names and optional fallback to the (~monthly growing) IAU star name list. The point to HIP numbers. (Special objects also have Gaia numbers, but that's IMO not needed.)