SSCore

SSCore is Southern Stars' astronomical core code, data, and telescope control library. It contains routines for astronomical calculations like time conversion, coordinate transformation, orbital mechanics, lunar and planetary position computation. It also contains functions for importing, storing, and combining data from a variety of astronomical catalogs. SSCore now includes code for controlling common amateur astronomical telescope mounts from Meade, Celestron, SkyWatcher, and Orion! The world's largest telescope manufacturer, Celestron, has commercially licensed SSCore for use with its products.

SSCore is written in highly portable, modern C++. It has been tested on MacOS, iOS, Android, Linux, Windows, and web browsers, via Emscripten. It uses common STL types and language features (string, vector, map; operator overloading) and stack-based memory management wherever possible to produce compact, highly efficient, optimized code.

This repository also includes simple test programs which serve as examples of how to use the API. Build environments for MacOS, iOS, Android, Windows, Linux, and Emscripten are included. The iOS version includes a plain C wrapper for the C++ classes which makes them useable from Swift. The Android version contains Java wrappers and JNI code which allows the C++ classes to be called from either a Java- or Kotlin-based Android environment.

License

SSCore is Copyright © 2020 Southern Stars Group, LLC. All rights reserved. Southern Stars grants you a license to use the SSCore code for any personal, private, research, or other non-commercial purpose.

If you wish to include any part of the SSCore code in a commercial product, please contact Southern Stars Group, LLC (timd@southernstars.com) for a commercial license.

SSCode

This directory contains the source code. Here's an overview of the C++ classes inside the SSCode directory:

• SSAngle: Classes for converting angular values from radians to degress/hours, minutes, seconds; and vice-versa.
• SSConstellation: This subclass of SSObject stores information for constellations and asterisms, including the official IAU constellation names, abbreviations, boundaries; and shape/figure data.
• SSCoordinates: This class converts rectangular and spherical coordinates between different astronomical reference frames (fundamental/ICRS, equatorial, ecliptic, galactic, local horizon) at a particular time and geographic location. It also handles precession, nutation, aberration, refraction, and other coordinate-related issues; and is used in ephemeris computation. Includes new expressions for precession, valid for +/- 200,000 years from the present time!
• SSEvent: This class computes times and circumstances of astronomical events like object rising/transit/setting, satellite passes, moon phases, conjuctions, oppositions, etc.
• SSFeature: This subclass of SSObject represents planetary surface features as listed in the Gazetteer of Planetary Nomenclature. A subclass SSCity stores additional information for populated locations on Earth's surface from GeoNames.Org.
• SSHTM: Implements the Heirarchal Triangular Mesh scheme for subdividing the sky recursively into trianglar regions, and storing/loading objects in those regions, including loading from asynchronous background threads.
• SSIdentifier: This class represents object identifiers used in a wide variety of astronomical catalogs with a unified system of 64-bit integers, and contains methods for converting identifiers from string representations ("HR 7001", "NGC 1976", etc.) to 64-bit integers and vice-versa.
• SSJPLDEphemeris: This class reads JPL's binary DE43x series of ephemeris files and computes very fast, sub-arcsecond-accurate lunar and planetary positions from them.
• SSPSEphemeris: Implements Paul Schlyter's planetary and lunar ephemeris, described here. This is the simplest way to compute planetary/lunar positions with an accuracy of 1-2 arc minutes; SSCore can use it as a fallback when the JPL DE ephemeris is not available. See note on VSOP2013 below.
• SSMatrix: Represents a 3x3 matrix, with routines for performing matrix and vector-matrix arithmetic.
• SSMoonEphemeris: Computes positions for the major moons of Mars, Jupiter, Saturn, Uranus, Neptune, and Pluto. For Earth's Moon, use SSJPLDEphemeris or SSPSEphemeris.
• SSMount: This class implements communication with common amateur telescope mount controllers over serial port and TCP/IP sockets. Supported protocols include Meade LX-200/Autostar, Celestron NexStar, and SkyWatcher/Orion SynScan.
• SSMountModel: This class is a C++ wrapper around the multi-star telescope mount alignment model code originally developed by Project Pluto.
• SSObject: Base class for all types of celestial objects (stars, planets, constellations, etc.) Also includes SSObjectArray, a class for storing a collection of objects and saving/loading them from CSV files, with built-in memory management.
• SSOrbit: This class stores Keplerian orbital elements, computes position/velocity at a given time from them, and vice-versa.
• SSPlanet: This subclass of SSObject represents all solar system objects (not just planets, but also moons, asteroids, comets, satellites, etc.) Includes methods for computing solar system object positions, velocities, magnitudes, sizes, and rotational parameters.
• SSSerial: This class contains routines for low-level serial (RS-232) communication on MacOS, Windows, and Linux. Currently not supported on iOS or Android.
• SSSocket: This class implements basic IPv4 and IPv6 network TCP and UDP socket communication. TCP server sockets are supported, but SSL is not supported. Includes a class for making basic HTTP 1.1 client requests and obtaining location from IP address.
• SSStar: This subclass of SSObject represents all objects outside the solar system, including stars, star clusters, nebulae, and galaxies. SSStar has special subclasses for double and variable stars, and for deep sky objects. Includes utility methods for stellar magnitude computations (absolute <-> apparent magnitude, etc.), Moffat-function stellar image profiles, and spectral type properties.
• SSTime: Classes for converting between Julian Dates and calendar dates/times; and between civil (UTC) and dynamic time (TDT).
• SSTLE: Routines for reading satellite orbital elements from TLE (Two/Three-Line Element) files, and computing satellite position/velocity from them using the SGP, SGP4, and SDP4 orbit models; and vice-versa.
• SSUtilities: A few useful string manipulation, angle conversion, and other utility functions that are not present in standard C++11.
• SSVector: Classes for converting points between spherical and rectangular coordinates, and for performing vector arithmetic operations.
• SSView: Represents a rectangular field of view of a part of the celestial sphere. Converts converts 3D positions on the celestrial sphere to 2D coordinates in the field of view (and vice versa) using a variety of map projections. Useful for astrometry, or rendering the sky onto a flat image or computer screen.

VSOP2013 and ELPMPP02

The VSOP2013 folder contains C++ code for two classes which implement the VSOP2013 planetary ephemeris and ELPMPP02 lunar ephemeris. These classes can use the original VSOP/ELP ephemeris series data files for full precision. They also contain truncated versions of these ephemeris series, embedded directly in the C++ code. These truncated, embedded versions are up to 100x smaller and faster than the original series, yet provide sub-arcsecond agreement with the full-precision series across their entire timespan, from the years -4000 to +8000.

By default, these classes are compiled to use the embedded series. You can strip out the embedded series by setting #define VSOP2013_EMBED_SERIES 0 and #define ELPMPP02_EMBED_SERIES 0 at the top of VSOP2013.hpp and ELPMPP02.hpp, then recompiling. This will make your compiled code several MB smaller. But then you will need to download the VSOP2013 and ELPMPP02 series files, and read them at runtime, to get valid computations.

JPL's DE ephemeris files are much faster than VSOP/ELP, but also much bulkier. JPL DE431 requires a 2.3 GB file to cover the same 12,000-year timespan of VSOP2013. So, by default, SSCore uses DE438 for planetary computations from 1950 to 2050; and uses VSOP/ELP outside those years.

You can build a version of SSCore without any dependency on VSOP2013 or ELPMPP02. Just remove those source files, then #define USE_VSOP_ELP 0 at the top of SSPlanet.cpp. The resulting code will use JPL DE438 when available, and fall back to Paul Schlyter's (fast, but not terribly accurate) formulae when DE438 is not available. You can also direct SSCore to use (or not to use) VSOP/ELP at runtime with SSPlanet::useVSOPELP().

Tetra3 Plate Solver

This work is a C++ implementation of the ESA Tetra3 lost-in-space algorithm, derived from the original python. Currently, this translation only includes the solver. The catalogue generator and source centroids extractor in the original python are not yet ported to C++. Performance-wise, this C++ implementation is roughly 6-10x faster than the original python code, running on the same hardware.

The original Tetra algorithm was developed by Julian Brown et. al. at MIT. The code repository developed by the original authors contains a C version, but that does not compile or run correctly.

Instead, I used Gustav Pettersson's python3 version as a starting point. It can create much larger databases, and Gustav provides excellent support.

I used a slightly-modified version of Carl Rogers' cnpy libray to read the NumPy .npz files from C++. The piece missing from cnpy was the ability to read structured NumPy arrays; I added that. Note that cnpy will no longer be needed in this project, when the C++ version of Tetra3 can build its own pattern databases.

The matrix singular value decomposition implementation came from svdfit.c, part of a NOAA GPS Toolbox. That implementation is a slightly modified version of the svdcmp() routine from the time-honored Numerical Recipes in C by W.H. Press, et. al.

The C++ implementation of the binomial cumulative distribution function at the top of Tetra3.cpp may have been written by ChatGPT.

The SSCode/Tetra3 directory contains the python code (tetra3.py) from which this C++ implementation was derived. The latest official tetra3.py has diverged from this since I began the C++ implementation, and I modified the python to read Southern Stars CSV-formatted star catalogs (as present in the SSData folder). A Tetra3 pattern database generated with my modified tetra3.py is included in the SSData/Stars subdirectory. See the README.md file there for more information.

Coding Style Standards

I comment copiously, especially function/method parameters and struct/class members. I use lots of whitespace, avoid TABs, and indent using four whitespaces. My braces use ANSI/ISO/BSD style, not K&R style. I start private member variable names with underscores. Raw pointer variable names start with p. Constants start with k.

Other general rules: functions should only have one return. Never use gotos. Split up functions longer than a page. Use polymorphism and avoid downcasting. Every rule has exceptions.

SSData

SSData is a collection of data on well-known astronomical objects, compiled and carefully vetted from a variety of modern astronomical catalogs and data sources. It includes:

• Solar System Objects: the major planets (including Pluto!) and their natural satellites, with orbital and physical characteristics from JPL Solar System Dynamics.. Also current asteroid and comet data from the Minor Planet Center, a selection of satellite TLE files from CelesTrak and N2YO, and JPL's latest planetary and lunar ephemeris.
• Stars: the brightest and nearest stars, compiled from NASA's SKY2000 Master Star Catalog, Hipparcos, RECONS, and other sources; with official IAU star names. A pattern database for the Tetra3 plate solver is also included.
• Deep Sky Objects: the Messier and Caldwell objects, with data from Wolfgang Steinicke's Revised NGC and IC catalogs, and enhanced using data from a few other sources.
• Constellations: the 88 IAU-sanctioned constellations, including official IAU boundary and shape data.

These files are mostly CSV-formatted text. They can easily be imported into a spreadsheet or edited manually. SSCore contains routines for reading and writing them as well.

SSTest

This directory contains a test program (SSTest.cpp), which hopefully serves as an example of how to use the C++ classes in the SSCode directory. It also contains build environments for MacOS, iOS, Android, Windows, Linux, and Emscripten. Building and running instructions for each platform follow.

• Android: open the SSTest/Android project with Android Studio 3.6 or later. You will also need the Android NDK r20 or later to compile the C++ code. Wait a minute for Gradle sync to complete. Then from the Build menu, select Make Project. After build completes, go to the Run menu and select Debug 'sstest'.
• MacOS: open SSTest.xcodeproj in the MacOS directory with Xcode 10 or later. From Xcode's Product menu, select Run. NOTE: by default, Xcode places the SSTest executable under ~/Library/Developer/Xcode/DerivedData, so SSTest won't know where to find the SSData folder. To fix this, from Xcode's File menu, select Project Settings..., then change Derived Data to Project-relative Location (DerivedData). This puts the DerivedData folder, which contains the SSTest executable, into the SSTest/MacOS folder adjacent to SSData.
• iOS: open SSTest.xcodeproj in the iOS directory with Xcode 10 or later. From Xcode's Product menu, select Run. This will launch a test program in the iPhone Simulator. There is no GUI, just text output which shows how to call the SSCore C++ classes from Swift using a plain-C wrapper (see ContentView.swift)
• Linux: cd to the Linux directory; then type make. After build completes, type ./sstest ../../SSData . The final . tells the sstest executable to place file output into the current directory.
• Windows: open SSTest.sln in Visual Studio 2017 or later. From Visual Studio's Build menu, select Build Solution. Then from the Debug menu, select Start Debugging (or Start Without Debugging if you have selected a Release configuration.) The Visual Studio project supports both x86 and x64 builds.
• Emscripten: cd to the Emscripten directory; then type make run. You will need to install the Emscripten build tools version 2.0.8 or later beforehand! Note, output files from the test run will not be persisted after the test executable quits.

SSMountTest is a simple test program for the SSMount telescope mount communication class, and its underlying SSSerial/SSSocket classes. SSMountTest can be compiled for MacOS, Windows, and Linux using the SSTest project (or Makefile) in the respective SSTeast directories for those platforms. SSMountTest.cpp does not build on iOS or Android, but the SSMount class works with socket communication on those mobile platforms.

SSTetraTest is a test program for the C++ Tetra3 plate solver. It can be compiled for MacOS, Windows, and Linux. The Tetra3 test executable takes one command-line argument: the path to the Tetra3.npz pattern database. The C++ Tetra3 code compiles and runs on iOS and Android, but this test program does not yet support mobile platforms.

Version History

• Version 1.0 - 12 Apr 2020: Initial public release.
• Version 1.1 - 12 May 2020: Added VSOP2013, ELPMPP02, SSMoonEphemeris, many fixes.
• Version 1.2 - 12 Aug 2020: Added SSView and SSHTM. Added rotational elements and planetographic coordinates to SSPlanet. Added magnitude utilities and Moffat functions to SSStar.
• Version 1.3 - 24 Nov 2020: Added SSFeature. Numerous fixes to other classes as a result of work on Nanoverse project.
• Version 1.5 - 21 Mar 2021: Added Jewish, Moslem, Indian calendars. Handle time zones with IANA names and daylight saving time. More robust angle and time parsing. Handle orbit computations over unlimited date ranges. Fix multi-threading issues; other misc. bug fixes.
• Version 1.6 - 25 Apr 2021: Added star spectral properties API. Add indexing and extensible file formats to SSHTM. Add filters to SKY2000, NGCIC, CSV import/export. Add geocentric velocity calculation, star and planet apparent motion calculations. Updated solar system and nearby star data. Misc. bug fixes.
• Version 1.7 - 05 Jun 2021: Added color index, rotation period, albedo, taxonomy to SSPlanet; added JPL DASTCOM file import; added Tycho and Tycho-2 star catalog import. Compute binary star separation and position. Import General Catalog of Variable Stars, Washington Double Star catalog. SSHTM can now be sublcassed. Misc. bug fixes.
• Version 1.8 - 21 Sep 2022: Added SSSerial, SSSocket, and SSMount for serial and socket-based communication with common amateur telescope mount controllers from Meade, Celestron, SkyWatcher, and Orion.
• Version 1.81 - 6 Oct 2022: Added IPv6 support to SSSocket. Added SSHTTP for basic HTTP 1.1 requests. Added SSSyntaMount subclass of SSMount for direct communication with Synta/SkyWatcher mounts.
• Version 1.9 - 27 Nov 2023: Added Tetra3 plate solver, test program, and pattern database. Added SSMountModel. Added code for importing GAIA DR3 and 10-pc sample. Misc warnings cleanup and minor fixes.