Jocular is a tool to support electronically-assisted visual astronomy.

Jocular's principal use is the observation of astronomical objects in near real-time by connecting a camera to a telescope or suitable lens. Jocular also supports session-planning through extensive deep sky object (DSO) databases, helps to manage your captures, enables the reloading of previously-captured images, and can be used to annotate your images.

Jocular is designed to be easy to use with a minimal, distraction-free interface, so you can focus on observing.

Jocular supports mono cameras and understands filters and can be used to create colour images via LRGB filters and real-time LAB colour space manipulation.

From v0.4.2 (22 March 2021) Jocular has experimental support for OSC cameras and binning.

Jocular supports the SX Lodestar camera and SX electronic filter wheel natively. Support for the SX Ultrastar is in the works. Other cameras can be used by outputting FITs to a directory that Jocular monitors.

Jocular is a 100% open-source Python cross-platform application and has been used extensively on OSX and Windows to date.


First, check that you have Python 3.4 or later on your system by opening a command/terminal window and typing:

python --version

If you don't have a suitable Python version, download it from python.org.

To install Jocular and its dependencies, type

pip install jocular

Note: if you are a Python user and have other Python applications, you might prefer to install Jocular in a virtual environment.

To run Jocular, simply type


Jocular needs a location where it can store your captures and other files such as observing lists and catalogues. The first time you run Jocular it will ask you to run it again but this time supplying the location of the data directory. First, create a suitable directory wherever you like, named however you wish, then run jocular again, this time providing the path to your data directory. For instance, if you called it joculardata and you are running the jocular command from the enclosing directory, you would just type

jocular --datadir joculardata

The first time Jocular runs it is quite slow as it does a fair bit of compilation. After 15 to 30 seconds or so you should see a window appear, and some 15 seconds later the window will look more like the one at the top of this page. The next time you start Jocular it will come up in a couple of seconds. Try it!

If you look inside the joculardata directory you will see some directories that Jocular has created, just waiting for your captures. If you'd like to explore the software using some existing captures, feel free to download these examples: Messier 100 (mono) | Messier 8 (LRGB).

Jocular uses a two level directory structure, the first for sessions and then within that, for each DSO. So to use these examples you should create a subdirectory of captures called, for example, examples, then expand the zip there. Then restart Jocular using the option to rebuild the previous observations file (this ensure that Jocular trawls through to find any new captures you have placed there manually):

jocular --rebuildobservations

Now when you click on the prev icon, the example should appear ready to be selected.

If things go wrong, or if you are just interested in seeing what Jocular is doing, start the program with the debug option:

jocular --log debug

You can also monitor Jocular via the status panel in the lower right corner of the tool itself.


The bare bones installation of Jocular via pip includes an object database with more than 40000 DSOs, more than adequate for session planning and snapshot labelling. You can also add your own catalogues as explained in the user guide. However, the advent of automatic annotation in v0.4 allows you to browse the contents of your images to a much greater depth. For that, you will need to download some of the catalogues contained in this section.

Minimally, you will need the platesolving database below. This should be unzipped and placed in a directory called platesolving within your Jocular data directory. If this is the only database you download, Jocular will annotate your images using the DSO catalogues that are automatically available when you install Jocular. Deeper annotation requires the other catalogues listed below. After unzipping, place them in the catalogues subdirectory of your Jocular data directory. Fire up Jocular and these catalogue entries will be available for automatic annotation.

Hearty thanks to all the professional and amateur astronomers who have compiled these catalogues and made them available!

Stars for Platesolving

This catalogue contains a subset of 17 million stars up to a G magnitude of 15.5 from the GAIA DR2.


This catalogue contains extensive information about more than 3.5 million galaxies from the Hyperleda database (2021).

Variable Stars

This catalogue contains over 2 million entries from the AAVSO database (2021).

Double/multiple Stars

This catalogue contains 153031 entries from the Washington Double Star (WDS) database (2020 version).


This catalogue contains more than 1.5 million quasars from the Milliquas database (2021 version).

Stellar Spectral Classes

This catalogue contains ~840 thousand entries from the Catalogue of Stellar Spectral Classifications (Skiff, 2009-2016), downloaded from Vizier.

Bright Stars

This catalogue contains 117955 stars from the Extended Hipparcos Catalogue (2012), downloaded from Vizier.

Compact Galaxy Group Members

This catalogue contains membership labels for the Hickson, Shakhbazian and Palomar Compact Galaxy groups, assembled from various sources (links and acknowledgement to follow).


You can find the source code on this GitHub page


Jocular is under active development (and use!) so expect to see some additional features added in the coming months. Some hot areas for development at the moment include:

  • native support for the SX Ultrastar camera
  • integration with INDI (and perhaps ASCOM via ALPACA)
  • direct control of the mount (slew to selected object)
  • minor planet/asteroid catalogues
  • simple photometry

Ideas and contributions are always welcome!


There is currently an intermittent and hard to trace bug that appears to freeze the GUI. This occurs on one run in 20 or so. In fact, the GUI is not frozen but responds to double-clicks! However, this rapidly gets tedious so the solution is to quit and start again. Since this bug only ever occurs at startup this workaround is adequate for now.

Object positions on the DSO screen do not currently reflect daylight savings. This will be fixed soon (fortunately they will be correct for the next 6 months!).

There is a bug in the demosaicing library that appears to affect Linux users.


The easiest way to get in touch is to contact me (user name: Martin Meredith) on stargazerslounge.com


Jocular has benefitted enormously from interactions with users. I'd particularly like to thank Bill S, Mike JW, AKB, Callump, Zak, Grant Privett, London David & CatBurglar for their patience, enthusiasm, and shared love of observing the beauty of the night sky.

Thanks also to the developers of the Kivy GUI framework which is the basis for the Jocular interface.