Embedded Files
In DXR, a mark consists of a Unity prefab and a mark script: a Unity prefab is a template of a game object that can be easily instantiated in a scene, and its properties can be programmatically mapped to data using Unity's scripting language described/implemented in a mark script. All mark prefabs should be placed under the Assets/DxR/Resources/Marks/ directory within a folder whose name is the same as the mark's name, e.g., the built-in cube mark is found in Assets/DxR/Resources/Marks/cube/cube.prefab. When deploying, you also need to put the name of the mark in the file Assets/DxR/Resources/Marks/marks.json. This naming convention is important for DXR to find all the available marks in the current Unity project. If no Mark script component is attached to the prefab, DXR automatically attaches the generic or default mark script to the prefab, which implements the generic visual channels (described in detail in the Encoding documentation):
- x, y, z (spatial positions)
- width, height, depth, size (render size)
- color, opacity (albedo of material)
- xrotation, yrotation, zrotation (rotation along axis)
- xdirection, ydirection, zdirection, length (direction arrow type mark points to, and length of the arrow).
To add new marks in addition to the built-in marks of DXR, the designer can create custom marks using one of two ways: 1) creating a custom prefab with generic mark script, or 2) creating a custom prefab with a custom mark script, which are explained below.
1. Creating a custom prefab with the generic mark script
1. Creating a custom prefab with the generic mark script
As mentioned earlier, if a custom prefab is placed in Assets/DxR/Resources/Marks/ without an attached mark script component, DXR will automatically attach the generic mark script which implements the generic visual channels. Therefore, to create a new mark using this approach, the designer simply has to create a prefab and place it in the folder, following the following naming convention: the folder name and the prefab name should be the same as the mark name, e.g., to add a new mark book, create a prefab Assets/DxR/Resources/Marks/book/book.prefab as illustrated below - to learn more about how to make Unity prefabs, please see this tutorial.
Once the prefab is created, you can then use it just like any generic mark as in the example below, using the custom book mark:
Notice in this example the use of fixed values for channels such as yrotation, zoffset, and yoffsetpct to tweak the setting/arrangement of the books, i.e., spine facing forward and not occluding keyword labels.
Other similar built-in custom marks without custom mark scripts are: sphere, cube, tick, rect, cone, and pinetree. For custom marks that use direction channels, the designer can specify the forward direction for the mark, i.e., where the prefab is facing by default, by setting the Forward Direction variable of the mark prefab via the Inspector view. If not modified, this is set to the up (0,1,0) direction by default.
2. Creating a custom prefab with a custom mark script
2. Creating a custom prefab with a custom mark script
If a custom prefab is placed in Assets/DxR/Resources/Marks/ with an attached mark script component, DXR will use this attached mark script as implementation for modifying the visual channels. Therefore, to create a new mark using this approach, the designer simply has to create a prefab with an attached mark script and place it in the folder, following the following naming convention: the folder name and the prefab name should be the same as the mark name, e.g., to add a new custom mark radialbar, create a prefab Assets/DxR/Resources/Marks/radialbar/radialbar.prefab with the attached custom mark script (e.g., MarkRadialBar.cs) as illustrated below (attached script component is highlighted in yellow):
To learn more about attaching scripts to objects, see this tutorial. You can use the following built-in examples of custom mark scripts as your guide: MarkRadialBar, MarkText. As demonstrated in these two, it doesn't matter where the actual script file is located, though for organizational reasons, it is preferred to place it together with the mark prefab under the mark folder as in the radialbar mark example.
The main rules for custom mark scripts are the following:
- extends the base Mark class
- provides implementation of: public override List<string> GetChannelsList() which returns the list of channels available for this mark (mainly for GUI interactions)
- provides implementation of: public override void SetChannelValue(string channel, string value) which internally handles the prefab modifications according to a given channel name and data value.
- for marks with direction, initializes the forwardDirection variable in the Start() method (if not modified, this is initialized to up (0,1,0) direction).
Below is an example of a visualization that uses the custom radialbar mark with its custom channels: latitude, longitude, and length - note that this example has been adapted from an existing implementation from: https://github.com/Dandarawy/Unity3D-Globe (provides the globe model and shader, as well as the data).
Explore other examples with custom marks and channels in the Examples page.
Google Sites
Report abuse