Details on Breaking Changes

The sections on this page describe some major breaking changes in version 0.20.0, together with instructions on how to adapt to the changes.

A New Renderable for Point Clouds

The RenderableBillboardsCloud class has been removed and replaced with a new Renderable type called RenderablePointCloud. This renderable includes some bug fixes as well as updates to the specifications in the asset related to color mapping, fading, and point sizing. These are made more explicit, to make it easier to use, and more understandable compared to its predecessor. The new Renderable also has support for CSV files, in addition to the previous SPECK file format. For full details on the renderable, check out the new content pages for point data.

The following sections describe how to convert an asset with a RenderableBillboardsCloud to the new format, or how to update a color map file (the .cmap data format has changed slightly). Finally, there is also a summary of the updated property names, that can hopefully be useful if you have Lua scripts or actions that require updating due to the use properties that have been updated or removed.

Note

Note that the previously existing RenderablePoints renderable has been removed in favor of the new RenderablePointsCloud.

How-to Update an Asset with a RenderableBillboardsCloud

Below is a code snippet showing an example of parts of an asset with a RenderableBillboardsCloud, before and after the update. The highlighted lines show the fields whose format or name has changed. See comments in the “After” example below for details.

local TullyGalaxies = {
  Identifier = "TullyGalaxies",
  Renderable = {
    Type = "RenderableBillboardsCloud",
    Labels = { ... },
    File = speck .. "tully.speck",
    Texture = textures .. "point3A.png",
    Unit = "Mpc",
    Opacity = 0.99,
    -- Things related to coloring
    Color = { 1.0, 0.4, 0.2 },
    ColorMap = speck .. "lss.cmap",
    ColorOption = { "prox5Mpc" },
    ColorRange = { { 1.0, 30.0 } },
    -- Fading
    FadeInDistances = { 0.001, 1.0 }, -- Fade in value in the same unit as "Unit"
    -- Things related to the size of the points
    ScaleFactor = 504.0,
    BillboardMinMaxSize = { 0.0, 7.0 }, -- in pixels
    EnablePixelSizeControl = true
  },
  ...
}
local TullyGalaxies = {
  Identifier = "TullyGalaxies",
  Renderable = {
    Type = "RenderablePointCloud",
    Labels = { ... },
    File = speck .. "tully.speck",
    Texture = textures .. "point3A.png",
    Unit = "Mpc",
    Opacity = 0.99,
    -- Things related to color have been combined into one group
    Coloring = {
      FixedColor = { 1.0, 0.4, 0.2 },
      -- Everything related to color mapping is also one component, which can be
      -- disabled to instead just use the FixedColor. If color mapping is not used
      -- at all in your asset, just skip this
      ColorMapping = {
        Enabled = true, -- Not required
        File = speck .. "lss.cmap",
        -- Combine each entry in ColorOption and ColorRange (line 13 and 14 above) into
        -- one "ParameterOption" per entry
        ParameterOptions = {
          { Key = "prox5Mpc", Range = { 1.0, 30.0 } }
        }
      }
    },
    -- Fading is moved into a separate component, which can also be disabled
    Fading = {
      Enabled = true, -- Not required
      FadeInDistances = { 0.001, 1.0 }, -- Fade in value in the same unit as "Unit"
    }
    -- Things related to the size of the points have been combined into one group
    SizeSettings = {
      ScaleExponent = 21.9, -- OBS! Recomputed based on previous ScaleFactor! See next section
      MaxSize = 0.3, -- No longer in pixels! Use a value that looks good to you
      EnableMaxSizeControl = true
    }
  },
  ...
}

Tip

Note that the Texture field is no longer required. If a texture is excluded, the points will be drawn as circles.

Compute ScaleExponent from ScaleFactor

The scaling of the points has been made more intuitive by changing the previous ScaleFactor property slightly, to make it more apparent that it affects an exponential scaling. See details on the point data page, but in general, with the new ScaleExponent the value is used as the exponent for 10^exponent to compute the world-scale size of the points.

The new ScaleExponent property can be computed from the previous ScaleFactor as:

\[ScaleExponent = \log_{10}(e^{ScaleFactor / 10})\]

Update Color Map Data Format

Previously, the first and last color entry in a .cmap file was implicitly interpreted as the color to use for values that are lower or higher than the specified range. However, this was not very clear and has been made more explicit in the update by using specific keywords for these colors. Here is an example of a color map before and after this change:

# Some comment about the color map. This is the one used for the Tully dataset,
# for example
6                # The number of colors
0.5 0.5 0.5 1.0  # gray (Was used for values outside range on the lower end)
0.0 0.8 0.8 1.0  # aqua
0.0 1.0 0.0 1.0  # green
0.0 1.0 0.0 1.0  # green
1.0 1.0 0.0 1.0  # yellow
1.0 0.5 0.0 1.0  # orange (Was used for values outside range on the upper end)
# Some comment about the color map. This is the one used for the Tully dataset,
# for example
4                # The number of colors (OBS! now excluding the outside range colors)
belowRange 0.5 0.5 0.5 1.0  # gray
0.0 0.8 0.8 1.0  # aqua
0.0 1.0 0.0 1.0  # green
0.0 1.0 0.0 1.0  # green
1.0 1.0 0.0 1.0  # yellow
aboveRange 1.0 0.5 0.0 1.0  # orange

Note that the belowRange and aboveRange colors do not have to be specified using this capitalization or order. As long as the keywords are spelled correctly, the lines for these colors can be put anywhere in the file.

The color maps that we provide with our default assets have been updated and should work fine. However, any custom color maps need to be updated to comply with the new format.

Tip

Note that with the 0.20.0 release, we do provide an asset with a number of common color maps, accessible by name, that might come in handy. Check out the example files for inspiration on how to use them.

Summary of Updated Properties

With just a few exceptions, the new RenderablePointCloud works very similarly to the previous RenderableBillboardsCloud. The behavior of the properties has not changed significantly, but the structuring of them has, and hence the name or URI that a property is accessed by may have to be updated.

Following is a table that summarizes the updated property names/URI:s, which can hopefully be useful if you have Lua scripts or actions that require updating due to the use properties that have been updated or removed.

RenderableBillboardsCloud (Before)

RenderablePointCloud (After)

Type

Comment

Color

Coloring.FixedColor

Color (Vec3)

ColorMap

Coloring.ColorMapping.ColorMap

String

UseColorMap

Coloring.ColorMapping.Enabled

Boolean

ColorOption

Coloring.ColorMapping.Parameter

Integer

OptionColorRange

Coloring.ColorMapping.ValueRange

Vec2

SetRangeFromData

Coloring.ColorMapping.SetRangeFromData

nil (Trigger Property)

UseLinearFiltering

(Removed)

SizeOption

Sizing.SizeMapping.Parameter

Integer

FadeInDistances

Fading.FadeInDistances

Vec2

Should now be set based on the origin of the dataset, rather than the world-space origin

DisableFadeIn

Fading.Enabled

Boolean

Inverted compared to the prevoius value

EnablePixelSizeControl

Sizing.EnableMaxSizeControl

Boolean

BillboardMinMaxSize

Sizing.MaxSize

Float

No longer a pixel value, so the value has to be updated

CorrectionSizeEndDistance

(Removed)

CorrectionSizeFactor

(Removed)

ScaleFactor

Sizing.ScaleExponent

Float

Can be computed based on the previous value, as described in the section above

Note that the full property URI would be of the form Scene.<IdentifierOfNode>.Renderable.<NameOfPropertyFromTableAbove>.

Some new features are that the data file can be loaded using a CSV file, and that the fading direction can be inverted. See the content page on point data for more details.

Updates to the RenderableStars

The RenderableStars class has been updated, which requires some changes to existing assets. Instead of specifying the Texture directly in the asset, it is now specified as part of the Halo group. As part of this change, the RenderableStars class has gained a number of additional features as well, for example the ability to configure the look of the halo textures through a Multiplier, Gamma, and Size values. Additionally, the same parameters exist for a Glare textures, where now stars can be rendered using one or both of these textures rendered on top of each other.

Before:

...
Texture = textures .. "halo.png"

After:

Halo = {
  Texture = textures .. "halo.png"
}
}

Changes in the openspace.navigation.saveNavigationState function

The format in which the navigation states are saved to a file on disk from this function has been changed. Prior to 0.20.0, this file was a Lua-file which was coded to return a table. As of 0.20.0, this fileformat is using JSON instead. This change affects both the openspace.navigation.saveNavigationState and the openspace.navigation.loadNavigationState functions.

If you have a pre 0.20.0 navigation state file that you want to convert, this is best done in a text editor using the following steps:

  1. Remove the leading return in the beginning of the file

  2. Replace all = with :

  3. All words “Position”, “Anchor”, “ReferenceFrame”, “Aim”, “Up”, “Yaw”, and “Pitch” should be surrounded by " and be written in lower case

  4. For the “Position” and “Up” entries, prepend the first value with "x":, the second value with "y":, and the third value with "z":

  5. (optional) Rename the file to have a .navstate extension

For example a pre 0.20.0 navigation state would be:

return {Anchor="Earth",Position={11701166.502990872,3397820.0813846793,19951812.217589088},Up={-0.8195835910478171,-0.23799315924271663,0.5211928562814687}}

After step 1:

{Anchor="Earth",Position={11701166.502990872,3397820.0813846793,19951812.217589088},Up={-0.8195835910478171,-0.23799315924271663,0.5211928562814687}}

After step 2:

{Anchor:"Earth",Position:{11701166.502990872,3397820.0813846793,19951812.217589088},Up:{-0.8195835910478171,-0.23799315924271663,0.5211928562814687}}

After step 3:

{"anchor":"Earth","position":{11701166.502990872,3397820.0813846793,19951812.217589088},"up":{-0.8195835910478171,-0.23799315924271663,0.5211928562814687}}

After step 4:

{"anchor":"Earth","position":{"x":11701166.502990872,"y":3397820.0813846793,"z":19951812.217589088},"up":{"x":-0.8195835910478171,"y":-0.23799315924271663,"z":0.5211928562814687}}