Defining an extrasolar system

In this little example we will define a made-up extrasolar system with two stars orbiting the common barycenter and four planets doing the same. We call the stars Exonia A and Exonia B, and the planets Exonia c, d, e and f. Additionally, we’ll give Exonia c a small moon called Exonia c1. The system we’ll create in this short tutorial can be downloaded directly from the download manager in Gaia Sky (with Gaia Sky 3.2.0+) or manually here.

Initial set up

First, we need to create the JSON file where we define the objects. Go to the $GS_DATA directory (see System Directories) and create the file exonia-system.json:

cd $GS_DATA
echo "{'objects':[]}" > exonia-system.json

We have created a file with no objects. In order for this file to be loaded at startup we have three options:

  1. Reference it in data-main.json

  2. Rename it to autoload-exonia-system.json

  3. Create a catalog file pointing to it, and select it in the catalog selection screen at startup.

In this guide we’ll use option 3. So create a new file catalog-exonia.json in the same directory. This file contains some metadata about the new catalog. Let’s have a look:

{
    "name" : "Exonia extrasolar system",
    "version" : 1,
    "type" : "catalog-other",
    "description" : "A made-up, partially procedurally
                    generated extra-solar system with
                    two stars, three planets and a moon.",
    "size" : 2600000,
    "nobjects" : 7,
    "data" : [
        {
            "loader": "gaia.cu9.ari.gaiaorbit.data.JsonLoader",
            "files": [ "data/exonia-system.json" ]
        }
    ]
}

As we can see, it has the catalog name, its version, its type, the description, the size, the number of objects and a pointer to the actual data file. All JSON files in Gaia Sky are loaded with the JsonLoader class, so that part is more or less constant.

Defining the objects

Now we are ready to start adding our objects. First, since all the objects orbit the barycenter of the system, we need an object to represent its position. This object must not be visible, but it must allow us to represent a position in space, and it must be the parent of all other objects in the system. We can do that with an object of type Invisible.

{
    "objects" : [
        {
            "names" : ["Exonia Center"],
            "ct" : ["Others"],
            "size" : 1E3,

            "parent" : "Universe",
            "impl" : "gaiasky.scenegraph.Invisible",

            "coordinates" : {
                "impl" : "gaiasky.util.coord.StaticCoordinates",
                "positionpc" : [20.0, 90.0, 10.0]
            }
        }
    ]
}

This object has the name Exonia Center. We will use this name in the "parent" attribute when we crate the rest of the objects. Since the barycenter of this system will not move, we use StaticCoordinates. Here he have used the property "positionpc", so we need to enter the position in parsecs in the internal reference system. We could have used "positionkm" to use kilometers, or simply "position" to use internal units.

The internal reference system is based on the equatorial system, so we need equatorial Carteisan coordinates. However, we can also use ecliptic or galactic cartesian coordinates by specifying a transformation:

{
    "coordinates" : {
       "impl" : "gaiasky.util.coord.StaticCoordinates",
       "positionpc" : [20.0, 90.0, 10.0],
       "transformName" : "galacticToEquatorial"
    }
}

Here, the properties "transformName" and "transformFunction" can be used interchangeably to specify the transformation.

Finally, we also accept spherical equatorial, galactic and ecliptic coordinates. They are set using "positionEquatorial" (alpha, delta, distance), "positionEcliptic" (l, b, distance) and "positionGalactic" (gal_lon, gal_lat, distance). The angles are in degrees and the distances are in parsecs. If you choose to use spherical coordinates, please do not specify a transformation!

Stars

Now, for each star we need an orbit object and a star object. The orbit is in charge of constructing the trajectory data and rendering it, while the star is the stellar object itself. We have two stars in the system, Exonia A and Exonia B. More information on the orbit format can be found here. Let’s see how we define them and then we go over the attributes:

{
    "name" : "Exonia A orbit",
    "color" : [1.0, 0.0, 1.0, 0.8],
    "ct": [ "Orbits", "Stars" ],

    "parent" : "Exonia Center",
    "impl" : "gaiasky.scenegraph.Orbit",
    "provider" : "gaiasky.data.orbit.OrbitalParametersProvider",

    "transformFunction" : "galacticToEquatorial",
    "newmethod": true,
    "orbit"                 : {
        "period" : 130.7655287755297,
        "epoch" : 2455198.0,
        "semimajoraxis" : 77112085.246326,
        "eccentricity" : 0.28862,
        "inclination" : 7.134,
        "ascendingnode" : 3.91,
        "argofpericenter" : 0.84,
        "meananomaly" : 307.80
    }
},
{
    "names" : ["Exonia A"],
    "color" : [1.0, 0.9213, 0.8818, 1.0],
    "colorbv" : 0.656,
    "ct" : "Stars",

    "absmag" : 2.85,
    "appmag" : 8.73,

    "parent" : "Exonia Center",
    "impl" : "gaiasky.scenegraph.Star",

    "coordinates" : {
        "impl" : "gaiasky.util.coord.OrbitLintCoordinates",
        "orbitname" : "Exonia A orbit"
    }
},
{
    "name" : "Exonia B orbit",
    "color" : [0.0, 1.0, 1.0, 0.8],
    "ct": [ "Orbits", "Stars" ],

    "parent" : "Exonia Center",
    "impl" : "gaiasky.scenegraph.Orbit",
    "provider" : "gaiasky.data.orbit.OrbitalParametersProvider",

    "transformFunction" : "galacticToEquatorial",
    "newmethod" : true,
    "orbit"                 : {
        "period" : 120.7655287755297,
        "epoch" : 2455198.0,
        "semimajoraxis" : 71112085.246326,
        "eccentricity" : 0.4,
        "inclination" : 0.93415027853740,
        "ascendingnode" : 130.74959784132,
        "argofpericenter" : 140.31984971,
        "meananomaly" : 0.40983227102735
    }
},
{
    "names" : ["Exonia B"],
    "color" : [0.9, 0.8213, 0.7818, 1.0],
    "colorbv" : 0.656,
    "ct" : "Stars",

    "absmag" : 4.85,
    "appmag" : 10.73,

    "parent" : "Exonia Center",
    "impl" : "gaiasky.scenegraph.Star",

    "coordinates" : {
        "impl" : "gaiasky.util.coord.OrbitLintCoordinates",
        "orbitname" : "Exonia B orbit"
    }
}

Note that we have to orbits and two stars. Orbits are objects of type gaiasky.scenegraph.Orbit. Each orbit is essentially a vessel for the orbital elements (period, semi-major axis, eccentricity, etc.). More information on the format and units can be found here. Since our Internal reference system is an equatorial system, we add the "galacticToEquatorial" transformation so that our reference plane is actually the galactic plane instead of Earth’s equatorial plane.

The stars are objects of type gaiasky.scenegraph.Star. Note that the parent of all objects is the invisible object Exonia Center. Additionally, the coordinates of the stars are provided by the respective orbit objects in the “coordinates” key. The rest is adding the star parameters like color, magnitudes, etc.

Colors can be specified in RGB or using the B-V color index. If both are specified, RGB takes precedence. In case Gaia Sky only finds the B-V color index, it translates it to RGB using this procedure.

Planets

Now, let’s have a look at the planets. They are very similar to the stars in that they also need orbit objects. They differ in the object type and attributes tough. Exonia e uses JPG images as textures, so at this point you should get the Exonia data pack, which contains these textures. The rest of the objects use procedurally generated data.

Since 3.2.0

Here is the definition of the planets:

{
    "name" : "Exonia c orbit",
    "color" : [0.3, 0.2, 0.9, 0.7],
    "ct": [ "Orbits", "Planets" ],

    "parent" : "Exonia Center",
    "impl" : "gaiasky.scenegraph.Orbit",
    "provider" : "gaiasky.data.orbit.OrbitalParametersProvider",

    "transformFunction" : "galacticToEquatorial",
    "newmethod": true,
    "orbit" : {
        "period" : 1325.85,
        "epoch" : 2455400.5,
        "semimajoraxis" : 353350171.0,
        "eccentricity" : 0.08862,
        "inclination" : 7.134,
        "ascendingnode" : 103.91,
        "argofpericenter" : 149.84,
        "meananomaly" : 307.80
    }
},
{
    "name" : "Exonia c",
    "color" : [0.5, 0.6, 1.0, 1.0],
    "size" : 2410.3,
    "ct" : "Planets",

    "absmag" : 0.5,

    "parent" : "Exonia Center",
    "impl" : "gaiasky.scenegraph.Planet",

    "coordinates" : {
        "impl" : "gaiasky.util.coord.OrbitLintCoordinates",
        "orbitname" : "Exonia c orbit"
    },

    "rotation"              : {
        "period" : 400.536,
        "axialtilt" : 0.0,
        "inclination" : 0.281,
        "meridianangle" : 200.39
    },
    "model"                 : {
        "args" : [true],
        "type" : "sphere",
        "params" : {
            "quality" : 400,
            "diameter" : 1.0,
            "flip" : false
        },
        "material" : {
            "height" : "generate",
            "diffuse" : "generate",
            "normal" : "generate",
            "specular" : "generate",
            "biomelut" : "data/tex/base/biome-smooth-lut.png",
            "biomehueshift" : 80.0,
            "noise" : {
                "seed" : 5229243,
                "scale" : 0.2,
                "type" : "simplex",
                "fractaltype" : "ridgemulti",
                "frequency" : 4.34,
                "octaves" : 10,
                "range" : [-1.8, 1.0],
                "power" : 4.0
            },
            "heightScale" : 3.0
        }
    },
    "cloud"         : {
        "size" : 2430.0,
        "cloud" : "generate",
        "noise" : {
            "seed" : 1234,
            "scale" : [1.0, 1.0, 0.4],
            "type" : "simplex",
            "fractaltype" : "ridgemulti",
            "frequency" : 4.34,
            "octaves" : 6,
            "range" : [-1.5, 0.4],
            "power" : 10.0
        },

        "params" : {
            "quality" : 200,
            "diameter" : 2.0,
            "flip" : false
        }
    },
    "atmosphere"    : {
        "size" : 2580.0,
        "wavelengths" : [0.7, 0.8, 0.9],
        "m_Kr" : 0.0025,
        "m_Km" : 0.0015,
        "m_eSun" : 1.0,
        "fogdensity" : 2.5,
        "fogcolor" : [1.0, 0.7, 0.6],

        "params" : {
            "quality" : 600,
            "diameter" : 2.0,
            "flip" : true
        }
    }
},
{
    "name" : "Exonia c1 orbit",
    "color" : [0.8, 0.4, 0.4, 0.7],
    "ct": [ "Orbits", "Moons" ],

    "parent" : "Exonia c",
    "impl" : "gaiasky.scenegraph.Orbit",
    "provider" : "gaiasky.data.orbit.OrbitalParametersProvider",

    "newmethod": true,
    "orbit"                 : {
        "mu" : 4.2e13,
        "period" : 1.2624407,
        "epoch" : 2455198.0,
        "semimajoraxis" : 23463.2,
        "eccentricity" : 0.00033,
        "inclination" : 1.791,
        "ascendingnode" : 0.370,
        "argofpericenter" : 0.233,
        "meananomaly" : 0.554
    }
},
{
    "name" : "Exonia c1",
    "color" : [0.5, 0.6, 1.0, 1.0],
    "size" : 410.3,
    "ct" : "Moons",

    "absmag" : 0.5,

    "parent" : "Exonia c",
    "impl" : "gaiasky.scenegraph.Planet",

    "coordinates" : {
        "impl" : "gaiasky.util.coord.OrbitLintCoordinates",
        "orbitname" : "Exonia c1 orbit"
    },

    "rotation"              : {
        "period" : 40.536,
        "axialtilt" : 0.0,
        "inclination" : 0.281,
        "meridianangle" : 200.39
    },
    "model"                 : {
        "args" : [true],
        "type" : "sphere",
        "params" : {
            "quality" : 400,
            "diameter" : 1.0,
            "flip" : false
        },
        "material" : {
            "height" : "generate",
            "diffuse" : "generate",
            "normal" : "generate",
            "specular" : "generate",
            "biomelut" : "data/tex/base/rock-smooth-lut.png",
            "biomehueshift" : 289.0,
            "noise" : {
                "seed" : 963249243,
                "scale" : 0.12,
                "type" : "simplex",
                "fractaltype" : "ridgemulti",
                "frequency" : 3.0,
                "octaves" : 8,
                "range" : [0.0, 1.0],
                "power" : 1.0
            },
            "heightScale" : 20.0
        }
    }
},
{
    "name" : "Exonia d orbit",
    "color" : [1.0, 0.7, 0.5, 0.7],
    "ct": [ "Orbits", "Planets" ],

    "parent" : "Exonia Center",
    "impl" : "gaiasky.scenegraph.Orbit",
    "provider" : "gaiasky.data.orbit.OrbitalParametersProvider",

    "transformFunction" : "galacticToEquatorial",
    "newmethod" : true,
    "orbit"                 : {
        "period" : 3851.7655287755297,
        "epoch" : 2455198.0,
        "semimajoraxis" : 719622085.246326,
        "eccentricity" : 0.1,
        "inclination" : 0.93415027853740,
        "ascendingnode" : 130.74959784132,
        "argofpericenter" : 180.31984971,
        "meananomaly" : 0.40983227102735
    }

},
{
    "name" : "Exonia d",
    "color" : [0.71, 0.32, 0.08, 1.0],
    "size" : 7439.7,
    "ct" : "Planets",

    "absmag" : -2.67,
    "appmag" : 5.73,

    "parent" : "Exonia Center",
    "impl" : "gaiasky.scenegraph.Planet",
    "refplane" : "equatorial",

    "coordinates" : {
        "impl" : "gaiasky.util.coord.OrbitLintCoordinates",
        "orbitname" : "Exonia d orbit"
    },

    "rotation"              : {
        "period" : 1407.509405,
        "axialtilt" : 2.1833,
        "inclination" : 7.005,
        "meridianangle" : 329.548
    },

    "model"                 : {
        "args" : [true],
        "type" : "sphere",
        "params" : {
            "quality" : 400,
            "diameter" : 1.0,
            "flip" : false
        },
        "material" : {
            "height" : "generate",
            "diffuse" : "generate",
            "normal" : "generate",
            "specular" : "generate",
            "biomelut" : "data/tex/base/biome-smooth-lut.png",
            "biomehueshift" : -15.0,
            "noise" : {
                "seed" : 993390,
                "scale" : 0.1,
                "type" : "simplex",
                "fractaltype" : "ridgemulti",
                "frequency" : 5.34,
                "octaves" : 10,
                "range" : [-1.4, 1.0],
                "power" : 7.5
            },
            "heightScale" : 14.0
        }
    },
    "cloud"         : {
        "size" : 7475.0,
        "cloud" : "generate",
        "noise" : {
            "seed" : 1983,
            "scale": [1.8, 1.8, 1.0],
            "type" : "simplex",
            "fractaltype" : "ridgemulti",
            "frequency" : 2.34,
            "octaves" : 4,
            "range" : [-1.5, 0.8],
            "power" : 7.0
        },

        "params" : {
            "quality" : 200,
            "diameter" : 2.0,
            "flip" : false
        }
    },
    "atmosphere"    : {
        "size" : 7730.0,
        "wavelengths" : [0.6, 0.56, 0.475],
        "m_Kr" : 0.0025,
        "m_Km" : 0.0015,
        "m_eSun" : 3.0,
        "fogdensity" : 4.5,
        "fogcolor" : [0.8, 0.9, 1.0],

        "params" : {
            "quality" : 600,
            "diameter" : 2.0,
            "flip" : true
        }
    }
},
{
    "name" : "Exonia e orbit",
    "color" : [0.2, 1.0, 0.5, 0.7],
    "ct": [ "Orbits", "Planets" ],

    "parent" : "Exonia Center",
    "impl" : "gaiasky.scenegraph.Orbit",
    "provider" : "gaiasky.data.orbit.OrbitalParametersProvider",

    "transformFunction" : "galacticToEquatorial",
    "newmethod": true,
    "orbit" : {
        "period" : 9905.85,
        "epoch" : 2455400.5,
        "semimajoraxis" : 1353350171.0,
        "eccentricity" : 0.08862,
        "inclination" : 9.134,
        "ascendingnode" : 83.91,
        "argofpericenter" : 149.84,
        "meananomaly" : 209.80
    }
},
{
    "name" : "Exonia e",
    "color" : [0.71, 0.32, 0.08, 1.0],
    "size" : 3389.7,
    "ct" : "Planets",

    "absmag" : -2.67,
    "appmag" : 5.73,

    "parent" : "Exonia Center",
    "impl" : "gaiasky.scenegraph.Planet",
    "refplane" : "equatorial",

    "coordinates" : {
        "impl" : "gaiasky.util.coord.OrbitLintCoordinates",
        "orbitname" : "Exonia e orbit"
    },

    "rotation"              : {
        "period" : 1407.509405,
        "axialtilt" : 2.1833,
        "inclination" : 7.005,
        "meridianangle" : 329.548
    },

    "model"                 : {
        "args" : [true],
        "type" : "sphere",
        "params" : {
            "quality" : 400,
            "diameter" : 1.0,
            "flip" : false
        },
        "material" : {
            "diffuse" : "data/tex/base/exoniae-diffuse.jpg",
            "emissive" : "data/tex/base/exoniae-emissive.jpg",
            "normal" : "data/tex/base/exoniae-normal.jpg",
            "metallic" : "data/tex/base/exoniae-metallic.jpg",
            "height" : "data/tex/base/exoniae-height.jpg",
            "heightScale" : 25.9848
        }
    },
    "atmosphere"    : {
        "size" : 3500.0,
        "wavelengths" : [0.55, 0.5, 0.45],
        "m_Kr" : 0.0025,
        "m_Km" : 0.0015,
        "m_eSun" : 3.0,
        "fogdensity" : 4.5,
        "fogcolor" : [0.8, 0.9, 1.0],

        "params" : {
            "quality" : 600,
            "diameter" : 2.0,
            "flip" : true
        }
    }
},
{
    "name" : "Exonia f orbit",
    "color" : [1.0, 1.0, 0.4, 0.7],
    "ct": [ "Orbits", "Planets" ],

    "parent" : "Exonia Center",
    "impl" : "gaiasky.scenegraph.Orbit",
    "provider" : "gaiasky.data.orbit.OrbitalParametersProvider",

    "transformFunction" : "galacticToEquatorial",
    "newmethod": true,
    "orbit" : {
        "period" : 11095.85,
        "epoch" : 2455400.5,
        "semimajoraxis" : 1453350171.0,
        "eccentricity" : 0.08862,
        "inclination" : 9.134,
        "ascendingnode" : 83.91,
        "argofpericenter" : 149.84,
        "meananomaly" : 209.80
    }
},
{
    "name" : "Exonia f",
    "color" : [0.71, 0.72, 0.78, 1.0],
    "size" : 3389.7,
    "ct" : "Planets",

    "absmag" : -2.67,
    "appmag" : 5.73,

    "parent" : "Exonia Center",
    "impl" : "gaiasky.scenegraph.Planet",
    "refplane" : "equatorial",

    "coordinates" : {
        "impl" : "gaiasky.util.coord.OrbitLintCoordinates",
        "orbitname" : "Exonia f orbit"
    },

    "rotation"              : {
        "period" : 1407.509405,
        "axialtilt" : 2.1833,
        "inclination" : 7.005,
        "meridianangle" : 329.548
    },
    "seed" : [9858457687, 11448],
    "randomize" : [ "model", "atmosphere" ],
    "cloud"         : {
        "size" : 3400.0,
        "cloud" : "generate",
        "noise" : {
            "seed" : 1234,
            "scale": [0.05, 0.05, 0.4],
            "type" : "gradval",
            "fractaltype" : "decarpenterswiss",
            "frequency" : 5.34,
            "octaves" : 9,
            "range" : [-0.1, 1.0],
            "power" : 2.0
        },

        "params" : {
            "quality" : 200,
            "diameter" : 2.0,
            "flip" : false
        }
    }
}

The orbits are essentially the same as in the case of stars. The objects are now of type gaiasky.scenegraph.Planet, and they define a rotation and a model. The rotation specifies the parameters of the orientation and rotation of the planet like the period, the axial tilt and the inclination. The model defines the 3D model object properties. In this case we use spheres. Within the model is the material, which defines the textures to use for each of the material attributes and optionally the procedural generation parameters. We also have clouds and atmospheres, but these are covered in the procedural generation section.

Here is a short clip of the system once loaded into Gaia Sky: