JSON data format#

Most of the entities and celestial bodies that are not stars in the Gaia Sky scene are defined in a series of JSON files and are loaded using the JsonLoader (JsonLoader). The format is very flexible and loosely mirrors the underlying object model, which is a scene graph tree.

An example about defining an extrasolar system with a couple of stars orbiting each other and a couple of planets can be found here.

Data morphology#

Before starting, we need to do a little detour to cover the data morphology. In Gaia Sky, objects organize and store their data into components, conforming to the Entity Component System (ECS) paradigm. Components are simple bags of data (attributes). Objects in Gaia Sky are assigned an archetype, which are simple component groups.

  • Archetype – an archetype is a definition of a group of components to create objects of a certain type. Every object has one and only one archetype. The archetype is specified with the "archetype" or the "impl" attributes, and take the name of the archetype (case sensitive!). For instance, the Planet archetype contains, amongst others, the components Base, Model, Coordinates and Atmosphere.

  • Component – a component is a simple bag of data. For example, the Base component contains a color, the object type, and the object name or names. Components are mostly hidden from users, as they are not defined directly in the JSON data files. Instead, components define what attributes are accepted by each object. An exhaustive list of all the attributes per component, together with descriptions and data types, is provided in Components.

Depending on the archetype of an object (i.e. depending on the components it has), objects are processed differently by different systems. Additionally, archetypes can extend other archetypes, so that the extending archetype gets all the components defined in the parent.

You can find a full description of all the archetypes and components in the data format, together with their attributes, here:

Objects vs Updates#

Every JSON file that contains objects must have a named array as the only top-level object in the file. Depending on the name of this array, two things can happen:

  • objects – when the array is named objects, it contains new objects to load.

  • updates – when the array is named updates, it contains updates to pre-existing objects.

Objects in updates arrays are kept and applied at the end of the loading stage, when all objects in the objects array have been loaded. They are matched by name.

So far, only the following objects and attributes can be updated:

  • material – material and all its sub-attributes. In particular, all regular textures, cubemaps and virtual textures: - diffuse, diffuseCubemap, diffuseSVT. - specular, specularCubemap, specularSVT. - normal, normalCubemap, normalSVT. - height, heightCubemap, heightSVT. - emissive, emissiveCubemap, emissiveSVT. - metallic, metallicCubemap, metallicSVT. - roughness, roughnessCubemap, roughnessSVT.

  • cloud – describes the cloud layer. Can also have a virtual texture. - diffuse, diffuseCubemap, diffuseSVT.

  • atmosphere – all its direct attributes.

  • rotation – all its direct attributes.

See the virtual textures section for some examples.

Basic attributes#

All archetypes have the Base, the Body and the GraphNode components. These components hold basic attributes, which can be specified with these (usually required) keys:

  • name – The name of the object. You can specify multiple names in a string array by using the names key.

  • color – The color of the object. This will translate to the line color in orbits, to the color of the point for planets when they are far away and to the color of grid lines.

  • componentType (alias: ct) – The ComponentType (see ComponentTypes). This is basically a string that will be matched to the entity type in ComponentType enum. Valid component types are Stars, Planets, Moons, Satellites, Atmospheres, Constellations, etc.

  • archetype (alias: impl) – The archetype name (or legacy package and class name of the implementing class).

  • parent – The name of the parent entity.

Additionally, different types of entities accept different additional parameters which are matched to the model using reflection. Here are some examples of these parameters:

  • sizeKm (with variants sizePc, sizeM, sizeAU, size) – The diameter of the entity. The unitless version uses internal units.

  • pos (with variants position, positionKm, positionPc, posKm, posPc) – The position of the object. This is the position at epoch (if the object has proper motion), or just a static position. Given in cartesian coordinates in the internal reference system.

  • labelColor – Color of the label of this object.

Below is an example of a simple entity, the equatorial grid:

{
    "name" : "Equatorial grid",
    "color" : [1.0, 0.0, 0.0, 0.5],
    "size" : 1.2e12,
    "componentType" : "Equatorial",

    "parent" : "Universe",
    "archetype" : "SphericalGrid"
}

Proper motions#

Objects of an archetype with a ProperMotion component can define proper motion attributes:

  • muAlpha (muAlphaMasYr) – The \(\mu_{\alpha\star}\), in mas/yr.

  • muDelta (muDeltaMasYr) – The \(\mu_{\delta}\), in mas/yr.

  • radialVelocity (radialVelocityKms) – The radial velocity in km/s.

  • epochJd (epochYear) – The proper motion epoch as a Julian date, or as a year fraction (2015.5).

Magnitudes#

Objects of an archetype with a Magnitude component can define an apparent and an absolute magnitude.

  • appMag – The apparent magnitude.

  • absMag – The absolute magnitude.

The apparent and absolute magnitudes are only used in celestial bodies. In stars, if only one is set, the other is computed automatically. If both are set, no consistency check is done against the distance. Also in stars, the absolute magnitude is used to compute a pseudo-size which is used for rendering purposes only. See the star rendering section for more information.

Labels#

All labels in Gaia Sky get the component type of the object they are attached to, plus the “Labels” component type. Here are some of the attributes related to labels. Attributes marked with a star (*) can only be applied to objects whose archetype has a Label component.

  • label* – Whether to render the label at all. Takes in a boolean.

  • labelColor – The color of the label, as a RGBA array.

  • forceLabel – Whether to force-display the label for this entity, regardless of distance and size.

  • labelPositionPc* (labelPositionKm, labelPosition) – Override the position of the label.

  • labelFactor* – Factor to apply to the size of the label for this object.

  • labelMax* – Internal rendering factor, should not be set externally unless you know what you are doing.

  • textScale* – Internal rendering factor, should not be set externally unless you know what you are doing.

Locations#

Locations (or location marks) are annotations shown on certain positions on the surface of objects. For example, locations are used on the Earth to display the locations of countries, cities, oceans and continents. Locations are always shown with coordinates [longitude,latitude] on the surface of a sphere of radius equal to the size of the parent object. This radius can be modified for individual locations using distFactor (see below). Location objects use the archetype Loc, and most of the attributes are in the LocationMark component.

As an example, let’s see a location mark for the city of Heidelberg:

 {
     "parent" : "Earth",
     "archetype" : "Loc",
     "componentType": [ "Locations" ],
     "name" : "Heidelberg",
     "locationType": "Cities",
     "markerTexture": "city",
     "location" : [8.68, 49.4],
     "sizeKm" : 5.3
}

  • parent – The parent object where the location mark should be displayed.

  • archetype – The archetype should be Loc.

  • componentType – Ideally, Locations.

  • name – Display name for the location label.

  • locationType – Optional. This is used to categorize the locations in the individual visibility window. If this is not present, locations are categorized using the parent object’s name.

  • markerTexture – The Location marker texture (image). Set to none to disable the marker image. Possible values are none, default, flag, city, town, landmark, or a path to a PNG image. If the path directs to a data package, the format is $data/[package-name]/path/to/file.png.

  • location – The location in degrees. Longitude and latitude.

  • sizeKm – The size of the location marker and label, in kilometers. This also determines visibility. Large locations disappear when we get closer to the object, unless we use ignoreSolidAngleLimit.

  • ignoreSolidAngleLimit – Ignore the solid angle upper limit when determining the visibility of this location. Setting this to true causes the location to not disappear, regardless of the camera distance.

  • color – The color of the marker image.

  • labelColor – The color of the label.

  • distFactor – Factor to apply to the parent object’s radius to get the distance from the center of the object, in case of non-spherical parent objects. This is essentially the radius, as the locations are given in [longitude, latitude, radius]. Typically the radius is that of the parent object, but this parameter overrides it.

Grids and other special objects#

There is a last family of objects which do not fall in any of the previous categories. These are grids and other objects such as the Milky Way (inner and outer parts). These objects usually have a special implementation and specific parameters, so they are a good example of how to implement new objects.

{
    "name" : "Galactic grid",
    "color" : [0.3, 0.5, 1.0, 0.5],
    "size" : 1.4e12,
    "componentType" : "Galactic",
    "transformName" : "equatorialToGalactic",

    "parent" : "Universe",
    "archetype" : "Grid"
}

For example, the grids accept a parameter transformName, which specifies the geometric transform to use. In the case of the galactic grid, we need to use the equatorialToGalactic transform to have the grid correctly positioned in the celestial sphere.