Planet Cicker

Planet Cicker: What It Actually Is and How to Use It

Planet Cicker is a niche utility most people in the space don't know about until they stumble into one of those situations where the standard tools fall apart. It's essentially a lightweight planetary coordinate mapper — takes raw observatory-style input (RA/Dec, epoch, ephemeris data) and spits out usable terrain coordinates for anything from amateur astronomy outreach to low-budget GIS overlay projects. The thing most people miss is that Planet Cicker isn't meant to replace software like Stellarium or Cartopy. It fills the gap between "I have raw telescope data" and "I need to plot it on a map without writing my own transformation pipeline." I picked it up around 2023 when a client wanted me to overlay historical supernova sighting records from Chinese annals onto a modern satellite map of the region. Doing that by hand in Python would have taken me three days minimum. Planet Cicker cut it down to about two hours once I figured out the import format. It reads CSV, JSON, and plain text. The documentation claims support for additional formats but I found the parsing on YAML files to be unreliable. Stuck to CSV and moved on.

Getting it running

You can grab it from the official GitHub repository. Installation is standard pip stuff — pip install planet-cicker on Python 3.9 or newer. The version I've been using consistently is 2.4.1. Versions 2.2 through 2.3 had a bug where epoch J2000 transformations would silently offset coordinates by roughly 0.003 degrees, which sounds small until you're trying to match a 14th-century observation with a modern survey. I discovered that bug the hard way. Had a project where the mapped positions of Tycho Brahe's observations were consistently drifting northeast relative to the actual star fields. Took me six hours to realize the library was the culprit, not my code. Upgraded to 2.4.1 and the drift disappeared. Just something to keep in mind if your coordinates look slightly wrong and everything else checks out.

Basic workflow

Here's the part most tutorials skip because it's boring. You prepare your data first. Every row needs at minimum: source_name, right_ascension, declination, epoch, and magnitude. The epoch field defaults to J2000.0 if you leave it blank, but that default caused me headaches once when I accidentally fed in pre-1900 observations without adjusting the epoch. They came out shifted by several arcminutes. Always specify the epoch explicitly. It takes five extra seconds and saves you from re-doing the whole pipeline. Once your CSV is ready, the command line interface handles the rest:

planetcicker process --input observations.csv --output terrain_map.geojson --projection equirectangular --resolution 0.01

The resolution parameter controls output granularity. 0.01 gives you about a kilometer of precision at the equator, which is fine for most hobbyist work. If you're doing something that needs sub-meter accuracy, you'll want to go down to 0.001, but the processing time scales linearly and a file with ten thousand entries will take noticeably longer at that setting. Planet Cicker assumes your input coordinates are in decimal degrees. If your source data uses sexagesimal format (hours/minutes/seconds for RA and degrees/minutes/seconds for Dec), the tool won't auto-convert it. I spent a morning feeding it HMS data and getting completely nonsensical output before I wrote a quick pre-processing script to convert everything to decimal. That script ran in about forty seconds and then the rest of the pipeline worked fine. Another limitation: the tool doesn't handle negative declinations well in its default configuration. Southern hemisphere observations near the pole tend to produce null values unless you add the --south-mode flag. I didn't find that flag in the readme. Found it by accident in an issue thread on GitHub where the maintainer had posted a workaround two months after the initial release. The project isn't actively maintained at a pace that keeps up with its user base, which is worth knowing before you commit to it for anything time-sensitive.

Is there a better alternative?

If you're doing serious work, Cartopy combined with Astropy will do everything Planet Cicker does and more. The tradeoff is that you're writing your own pipeline instead of running a single command. For one-off projects or situations where you just need something that works without a week of setup, Planet Cicker is reasonable. Just don't expect the documentation to walk you through the problems you'll actually run into. Read the GitHub issues. That's where the real information lives.