RenderableVectorField

Inherits Renderable

Renders vectors from a given 3D volumetric dataset or a sparse point-like dataset, optionally including color mapping and custom filtering via Lua script.

If mode is set to Volume, the vector field is defined on a regular 3D grid specified by Dimensions, and occupies the spatial domain defined by MinDomain and MaxDomain.

If mode is set to Sparse, the vector field is defined by the position given by the Cartesian coordinates and direction (e.g., velocity).

The Stride parameter controls how densely vectors are sampled from the volume (a stride of 1 renders every vector).

There are several coloring methods to choose from. By default, the vectors are colored with a fixed color. Other options include using a color map to color the vectors by the direction magnitude. And lastly, color by direction, similar to a 3D model normal map as follows: +X -> Red, -X -> Cyan +Y -> Green, -Y -> Magenta +Z -> Blue, -Z -> Yellow

Members

Name	Documentation	Type	Description	Optional
Mode	The mode determines the type of vector field data that is loaded. In volume mode, the vector field is computed from a 3D volume data file, the volume is mapped to the domain [min, max]. In sparse mode, the vector field is computed given the specified position and velocity components from a CSV file.	String	In list { Volume, Sparse }	No
Coloring	Settings related to the coloring of the vectors, such as a fixed color, color map, etc.	Table	Table parameters	Yes
DimInAtmosphere	Decides if the object should be dimmed (i.e. faded out) when the camera is in the sunny part of an atmosphere.	Boolean	Value of type ‘Boolean’	Yes
Enabled	Determines whether this object will be visible or not.	Boolean	Value of type ‘Boolean’	Yes
FilterByLua	If enabled, the vector field is filtered by the provided custom Lua script.	Boolean	Value of type ‘Boolean’	Yes
LineWidth	The width of the vector lines.	Double	Greater than: 0	Yes
Opacity	This value determines the opacity of this renderable. A value of 0 means completely transparent.	Double	In range: ( 0, 1)	Yes
RenderBinMode	A value that specifies if the renderable should be rendered in the Background, Opaque, Pre-/PostDeferredTransparency, Overlay, or Sticker rendering step.	String	In list { Background, Opaque, PreDeferredTransparent, Overlay, PostDeferredTransparent, Sticker }	Yes
Script	This value is the path to the Lua script that will be executed to compute the filtering. The script needs to define a function ‘filter’ that takes the current voxel position (x, y, z) given in galactic coordinates, and the velocity vector (vx, vy, vz). The function should return true/false if the voxel should be visualized or discarded, respectively.	File	Value of type ‘File’	Yes
Sparse	Settings related to using a sparse dataset.	Table	Table parameters	Yes
Stride	Controls how densely vectors are sampled from the volume. A stride of 1 renders every vector.	Integer	Value of type ‘Integer’	Yes
Tag	A single tag or a list of tags that this renderable will respond to when setting properties.	Table, or String	Value of type ‘Table’, or Value of type ‘String’	Yes
Type	The type of the renderable.	String	Value of type ‘String’	Yes
VectorFieldScale	Scales the vector field lines using an exponential scale.	Double	Greater than: 1	Yes
Volume	Settings related to using a volumetric dataset.	Table	Table parameters	Yes

Inherited members from Renderable

Name	Documentation	Type	Description	Optional
DimInAtmosphere	Decides if the object should be dimmed (i.e. faded out) when the camera is in the sunny part of an atmosphere.	Boolean	Value of type ‘Boolean’	Yes
Enabled	Determines whether this object will be visible or not.	Boolean	Value of type ‘Boolean’	Yes
Opacity	This value determines the opacity of this renderable. A value of 0 means completely transparent.	Double	In range: ( 0, 1)	Yes
RenderBinMode	A value that specifies if the renderable should be rendered in the Background, Opaque, Pre-/PostDeferredTransparency, Overlay, or Sticker rendering step.	String	In list { Background, Opaque, PreDeferredTransparent, Overlay, PostDeferredTransparent, Sticker }	Yes
Tag	A single tag or a list of tags that this renderable will respond to when setting properties.	Table, or String	Value of type ‘Table’, or Value of type ‘String’	Yes
Type	The type of the renderable.	String	Value of type ‘String’	Yes

Table parameters for Coloring

Settings related to the coloring of the vectors, such as a fixed color, color map, etc.

• Optional: Yes

Name	Documentation	Type	Description	Optional
ColorMap	The path to the color map file used for coloring the vector field.	File	Value of type ‘File’	Yes
ColorMappingDataRange	The magnitude data range used to normalize the magnitude value for color lookup. Computed from the volume data if unspecified.	Vector2<double>	Value of type ‘Vector2’	Yes
ColorMode	Controls how the vectors are colored. “Fixed” color all vectors with the same static color. “Magnitude” color the vector field based on the min and max magnitudes defined in the volume. “Direction” colors the vector based on their direction, as follows: +X -> Red, -X -> Cyan, +Y -> Green, -Y -> Magenta, +Z -> Blue, -Z -> Yellow.	String	In list { Fixed, Magnitude, Direction }	No
FixedColor	The color of the vectors, when no color map is used.	Color4	Value of type ‘Color4’	Yes

Table parameters for Sparse

Settings related to using a sparse dataset.

• Optional: Yes

Name	Documentation	Type	Description	Optional
FilePath	The path to the CSV file containing the vector field data.	File	Value of type ‘File’	No
Vx	Specifies the column name for the vx velocity component.	String	Value of type ‘String’	Yes
Vy	Specifies the column name for the vy velocity component.	String	Value of type ‘String’	Yes
Vz	Specifies the column name for the vz velocity component.	String	Value of type ‘String’	Yes
X	Specifies the column name for the x coordinate.	String	Value of type ‘String’	Yes
Y	Specifies the column name for the y coordinate.	String	Value of type ‘String’	Yes
Z	Specifies the column name for the z coordinate.	String	Value of type ‘String’	Yes

Table parameters for Volume

Settings related to using a volumetric dataset.

• Optional: Yes

Name	Documentation	Type	Description	Optional
Dimensions	The dimensions of the volume data.	Vector3<int>	Value of type ‘Vector3’	No
MaxDomain	The max domain values that the volume should be mapped to.	Vector3<double>	Value of type ‘Vector3’	No
MinDomain	The min domain values that the volume should be mapped to.	Vector3<double>	Value of type ‘Vector3’	No
VolumeFile	The path to the file containing the volume data.	File	Value of type ‘File’	No

Asset Examples

Color Mapped

This example creates a vector field where vector colors are determined by a color mapping.

The color mapping is applied to the magnitude of each vector, which is computed internally from the vector components. The color mapping range is automatically computed from the minimum and maximum magnitude values present in the dataset.

-- Note that the color map is loaded from another asset. This is a utility asset that
-- includes some common color maps for general usage.
local colormaps = asset.require("util/default_colormaps")

-- Load the volume data from OpenSpace servers
local volume = asset.resource({
  Name = "Vector Field - Example",
  Type = "HttpSynchronization",
  Identifier = "vectorfield_volume",
  Version = 1
})

local Node = {
  Identifier = "RenderableVectorField_Example_ColorMapped",
  Renderable = {
    Type = "RenderableVectorField",
    Mode = "Volume",
    VectorFieldScale = 8.0,
    Volume = {
      VolumeFile = volume .. "vectorfield_16x16x16_magnitude_radial.bin",
      MinDomain = { -5000.0, -5000.0, -5000.0 },
      MaxDomain = { 5000.0, 5000.0, 5000.0 },
      Dimensions = { 16, 16, 16 }
    },
    Coloring = {
      ColorMode = "Magnitude";
      ColorMap = colormaps.Uniform.Viridis,
      FixedColor = { 1.0, 0.7, 0.5, 1.0 }
    }
  },
  GUI = {
    Name = "RenderableVectorField - Color Mapped",
    Path = "/Examples"
  }
}


asset.onInitialize(function()
  openspace.addSceneGraphNode(Node)
end)

asset.onDeinitialize(function()
  openspace.removeSceneGraphNode(Node)
end)

Lua Filtered

This example creates a vector field where the visibility of individual vectors is controlled using a Lua filter.

The Lua filter allows custom logic to determine whether a vector should be rendered or hidden based on its position and direction. This makes it possible to selectively visualize regions or directional subsets of the vector field, such as hiding vectors below a magnitude threshold or excluding vectors outside a specific spatial region.

The filter is provided as a separate Lua script asset. The script is executed at runtime and changes to the filter logic are applied by updating that asset.

-- Load the volume data from OpenSpace servers
local volume = asset.resource({
  Name = "Vector Field - Example",
  Type = "HttpSynchronization",
  Identifier = "vectorfield_volume",
  Version = 1
})

local Node = {
  Identifier = "RenderableVectorField_Example_LuaFilter",
  Renderable = {
    Type = "RenderableVectorField",
    Mode = "Volume",
    VectorFieldScale = 8.0,
    Volume = {
      VolumeFile = volume .. "vectorfield_16x16x16.bin",
      MinDomain = { -5000.0, -5000.0, -5000.0 },
      MaxDomain = { 5000.0, 5000.0, 5000.0 },
      Dimensions = { 16, 16, 16 }
    },
    FilterByLua = true,
    Script = asset.resource("script/filter.lua")
  },
  GUI = {
    Name = "RenderableVectorField - Lua Filter",
    Path = "/Examples"
  }
}


asset.onInitialize(function()
  openspace.addSceneGraphNode(Node)
end)

asset.onDeinitialize(function()
  openspace.removeSceneGraphNode(Node)
end)

Basic

This example creates a basic vector field visualization from a volumetric data file.

-- Load the volume data from OpenSpace servers
local volume = asset.resource({
  Name = "Vector Field - Example",
  Type = "HttpSynchronization",
  Identifier = "vectorfield_volume",
  Version = 1
})

local Node = {
  Identifier = "RenderableVectorField_Example",
  Renderable = {
    Type = "RenderableVectorField",
    Mode = "Volume",
    VectorFieldScale = 8.0,
    Volume = {
      VolumeFile = volume .. "vectorfield_16x16x16.bin",
      MinDomain = { -5000.0, -5000.0, -5000.0 },
      MaxDomain = { 5000.0, 5000.0, 5000.0 },
      Dimensions = { 16, 16, 16 }
    }
  },
  GUI = {
    Name = "RenderableVectorField - Basic",
    Path = "/Examples"
  }
}


asset.onInitialize(function()
  openspace.addSceneGraphNode(Node)
end)

asset.onDeinitialize(function()
  openspace.removeSceneGraphNode(Node)
end)

Sparse

This example creates a vector field visualization from a sparse point-cloud datase, provided in a CSV data file with one row per vector.

Optionally, one can specify the column names for the position and direction. Otherwise, x, y, z, and vx, vy, vz are assumed as the position and direction columns, respectively.

local Node = {
  Identifier = "RenderableVectorField_Example_Sparse",
  Renderable = {
    Type = "RenderableVectorField",
    Mode = "Sparse",
    VectorFieldScale = 15.0,
    Sparse = {
      FilePath = asset.resource("../renderablepointcloud/data/dummydata.csv")
    }
  },
  GUI = {
    Name = "RenderableVectorField - Sparse",
    Path = "/Examples"
  }
}


asset.onInitialize(function()
  openspace.addSceneGraphNode(Node)
end)

asset.onDeinitialize(function()
  openspace.removeSceneGraphNode(Node)
end)