Getting Started With Planet San Jose Costa Rica Software
I first ran into this around 2019 when a colleague in my department needed a local sky simulation tool and found that Planet San Jose Costa Rica was one of the few setups that handled Central American latitudes without breaking. It is not a consumer-grade app. It is a utility you set up once and then forget about, which is exactly why most people either love it or never get past the first install. The package includes a command-line renderer and a small GUI wrapper. The CLI is where everything actually happens. You feed it a date, a latitude, a longitude, and an altitude, and it outputs an image or a sequence of frames. The default values are set for San Jose, but you can point it at anywhere. That flexibility is the whole reason people use it instead of buying something like Stellarium or skyField. The installer on Linux is straightforward if you are used to building from source. On macOS you need to handle the Qt dependency manually unless you want to use the older prebuilt bundle, which tends to have rendering artifacts near the horizon. Windows users will probably just use the MSI installer. It works, but it is not very well documented.
My main complaint has always been the documentation. There is no single place where the flags are listed cleanly. You end up reading the help output and then poking at example scripts in the samples directory until things render correctly. The sample scripts are decent though, and they cover the common cases: single images, time-lapse sequences, and ephemeris generation for a given location.
Working through a real installation problem
Last year I hit an issue where the horizon mask was not loading correctly for any location south of Quito. The elevation data from the built-in SRTM grid was incomplete for parts of southern Central America, which caused the renderer to interpolate flat terrain where there were actually steep mountain ranges. The consequence was that objects like the Pleiades would appear above the horizon in the simulation even though they should have been obscured. It looked wrong fast. The fix was to swap out the default terrain file and load a higher-resolution SRTM tile for the specific region. You do that by pointing the TERRAIN_FILE environment variable at a custom .dem file before launching the renderer. I grabbed the appropriate tile from the ASF DAAC archive, reprojected it to WGS84, and ran a quick merge script against the existing tiles. After that the horizon mask rendered correctly. It took about forty minutes total, but the default setup does not warn you that this problem exists.
Get the Full Details
Output formats and practical use cases
The software can output PNG, TIFF, and FITS files, plus raw sky coordinates in CSV. For most people the PNG export is enough. If you are doing something like planning telescope observing sessions or generating accurate star charts for a presentation, you will want the FITS output so you can overlay photometric data later. The CSV coordinate export is useful if you are writing a script to automate sky checks across multiple nights. One thing people miss is that the software can generate a full sky map at any hour angle. You do not have to pick a fixed time. You can specify a range and it will step through the rotation automatically. That saves you from running the command thirty times by hand and stitching the results together, which is the slow way to do it. Here is a quick example of a typical command for a single night observation window:
planet-sj --lat=9.9281 --lon=-84.0907 --date=2025-06-15 --start=21:00 --end=03:00 --output=out.png --format=fits That command assumes you have the binary on your PATH. If you installed from source, it might be in a subdirectory. Check the README in the build folder for the exact path. The --format flag controls the output type. Using FITS without a subsequent conversion step will give you a file that looks empty if you open it in an image viewer because it is stored in a scientific format, not a display format. That is normal and not a bug. Use ds9 or Astropy to view FITS files properly.
Common pitfalls and what the software cannot do
This tool will not give you real-time live video of the sky. It is a simulator and a chart generator, not a camera interface. If you are looking for something that connects to your telescope and shows you what the mount is pointing at right now, this is not it. You need a separate plate-solving or guiding application for that. Another limitation: atmospheric refraction modeling is basic. Near the horizon, objects can be displaced by a degree or so depending on temperature and pressure conditions, and the built-in model uses a standard atmosphere. If you need precision within arcminutes at low elevations, you will have to apply your own correction factors or switch to a more advanced ephemeris library like Swisseph. The software also does not include a built-in planetarium UI with mouse panning and zooming like you get with commercial products. The GUI wrapper exists, but it is minimal. Most power users skip it entirely and work from the command line anyway.
Performance notes
A single full-sky render at medium resolution takes roughly ten to fifteen seconds on a modern CPU. Time-lapse sequences scale linearly with the number of frames. A four-hour sequence at one frame per minute generates two hundred and forty frames and usually finishes in under five minutes on the same hardware. GPU acceleration is not currently supported, so if you need to generate thousands of frames for a project, plan accordingly. If you are on a constrained system and need faster turnaround, you can reduce the render resolution or use the --fast flag, which disables some of the finer detail calculations. The difference is small for most purposes but cuts render time roughly in half. I have been running this in a small observatory setting for several years now and it has not let me down except for the terrain resolution issue I mentioned, which is easy to work around once you know it exists. It is not the most polished tool you will find, but for straightforward sky simulation at a fixed Central American location, it does what it needs to do without costing anything.
