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:
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 (Vec3) |
|
|
|
String |
|
|
|
Boolean |
|
|
|
Integer |
|
|
|
Vec2 |
|
|
|
|
|
|
(Removed) |
||
|
|
Integer |
|
|
|
Vec2 |
Should now be set based on the origin of the dataset, rather than the world-space origin |
|
|
Boolean |
Inverted compared to the prevoius value |
|
|
Boolean |
|
|
|
Float |
No longer a pixel value, so the value has to be updated |
|
(Removed) |
||
|
(Removed) |
||
|
|
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"
}
}