-
Notifications
You must be signed in to change notification settings - Fork 4
NonAnimatedScene
Note: This page is somewhat outdated, as we now have a single scene with multiple tables instead of one scene per city type.
This page describes how to set up an ordinary code-city scene without evolution animation. If you want to animate the evolution of a city, follow the steps described here.
The scene MainScene contains all the necessary objects already. You can use it as a starting point for your own scene.
Instead of following the manual steps below, it's also possible to quickly setup the scene by doing the following:
- Add an empty GameObject to your scene, and name it "Player Settings".
- Attach the "Player Settings" script component to it.
- Click on "Add required objects to scene".
- If your scene should be compatible with the HoloLens, you need to follow the "MixedReality setup" steps further down, as this can't yet be done automatically.
Your scene must contain the following game objects:
- A Directional Light.
- Some kind of table with a component SEE.GO.Plane upon which the code cities are to be put. Any kind of game object representing this table can be used. The Scale Factor of the SEE.GO.Plane must be a factor to adjusting the table's scale units to Unity units. If the table is a Unity cube, the factor should be 1; but there are other kinds of objects for which one scale unit is not exactly on Unity unit. The table object must be tagged by CullingPlane.
- A VRPlayer as an instance of the player rig prefab by SteamVR (Assets/SteamVR/InteractionSystem/Core/Prefabs/Player.prefab). Attached to it must be an XRChartAction, XRRay, and XRPlayerMovement component (see below). The name of that game object must be "VRPlayer".
- A game object named "DesktopPlayer" with a Camera, Event System, and Standalone Input Module (comes along with the Event System). In addition to that the SEE components DesktopPlayerMovement and DesktopChartAction must be attached. The attribute Focused Object of the DesktopPlayerMovement must be a SEE.GO.Plane component of the table the code cities will be placed on.
- A game object named "PlayerSettings" with SEE's PlayerSetting component.
- A game object named "InControl" created by the menu "GameObject=>InControl=>Manager". This object is required to support gamepads and touchscreens with virtual gamepad controllers. It must have the following child game objects: "Touch Camera", "Touch Stick Left", "Touch Stick Right", and "Touch Button Control". These implement the virtual controllers for touchscreens. They can be created by "GameObject=>InControl=>Touch=>Manager" and then in the inspector when you click on the "InControl" object through the buttons "Create Button Control" and "Create Stick Control". The "Touch Stick Left" should have "Left Stick" as option "Target" and the "Touch Stick Right" should have "Right Stick" as option "Target". The "Touch Button Control" must have "Left Trigger" as option "Target". The targets are the actions defined in Unity's input manager (these were added by InControl)
- A game object named "ChartManager" tagged by "ChartManager" with a component that is an instance of class ChartManager and another component that is an instance of class Animator (the attribute Controller of this Animator must be the ChartManager component -- its sibling). This game object must have a child game object named "ChartsVR" that has a component of class ChartPositionVr attachted to it (the attribute Camera Transform must refer to the transform of the VR Camera). For your convenience, a prefab "ChartManager" exists that you may add to the scene.
If you want to (optional, purely for the aesthetics), you can select "Window=>Rendering=>Lighting Settings" to open the lighting settings. Click on the right dotted circle next to the field "Skybox Material" to select WispySkyboxMat.
A way to automatically add these objects to the scene is still in development. However, for now, these steps must be followed.
In order to make the new scene compatible with the HoloLens, several other requirements exist in addition to the ones above:
- You need to add the MixedRealityToolkit GameObject (with this exact name) to the scene. This can be done by selecting Mixed Reality Toolkit -> Add to Scene and Configure...
- A game object named MRPlayer must exist. This will be the camera for the HoloLens player.
The easiest way to create this object is by copying the DesktopPlayer and adjusting it.
The game object must meet the following requirements:
- It must be tagged MainCamera.
- It needs to be at position
(0,0,0)with a scale of(1,1,1). - It should have a MixedRealityInputModule as a component.
- It should not have any other input modules (such as "Standalone Input Module") attached.
- It should not have scripts for other platforms (such as "Desktop Player Movement") attached.
- Any game object which either only makes sense on different platforms or which isn't strictly necessary for the user (e.g. purely decorative) must be tagged as "Decoration." Examples for this would be the Chair, Light, or Sofa from the MainScene. These objects will then be disabled when playing on HoloLens, as they're not necessary in mixed reality and cause performance to worsen on mobile GPUs. This is especially relevant for the seated scale (see below), where such objects can be distracting to the user.
- Note that Portals will be deactivated on HoloLens due to the fact that we use a different material with the MRTKShader.
Finally, you need to choose a mixed reality scale. This scale will define several parameters of the mixed reality environment. The scales are documented on this page, but a short comparison of the two most important scales (Seated and Room) has been included here:
| Seated scale | Room scale |
|---|---|
| Stationary position (user doesn't move) | User moves within room |
| Position CodeCities relative to user | Position CodeCities relative to room |
| Floor isn't defined | Floor is defined |
| "Recenter view" button possible | User walks around the room |
| Origin at head level | Origin at floor level |
Choose your desired scale in the Player Settings game object, at Experience Scale. Depending on which scale you choose, you need to consider different points. Additionally, be aware that the Room Scale is much better suited for Multiplayer, due to the fact that multiple users interact with objects and each other, thereby requiring basically fixed positions.
- A game object named CityCollection must exist. As a component, it must have a GridObjectCollection.
Code cities will be positioned using this object.
- Configure the GridObjectCollection component in the inspector to arrange the code cities in the way you want. Note that Cell Width will be set automatically, so changes to that field won't matter.
- Move this GameObject to the front of the user (i.e. in front of MRPlayer). This way, users on a HoloLens don't have to look around and search for the code cities after loading the scene. Instead of placing the CityCollection on the same level as the user, consider moving it down a bit, as the user most likely wants to look at it from above instead of from the side.
- Instead of scaling this object, it may be a better idea to use the City Scaling Factor in the Player Settings, which controls how code cities should be scaled at startup relative to their usual scale on other platforms.
- Be careful to use sensible scaling for your objects (1 unit in Unity equals about 1 meter.)
- The room the user walks around in shouldn't be bigger than 5 meters, otherwise a World Scale may be necessary.
- The City Scaling Factor in Player Settings will not be applied, and a CityCollection (if it exists) will not be used.
Simply open your Player Settings GameObject, choose your "City type" from the dropdown, enter a name for the city at "Name of new city" and click on the button "Create city." The new code city will be added to the scene using the given name and type.
This section is not up to date! Several required components for the city object are not documented.
Add a new 3D cube GameObject to your city. We will call this the city object in the following. It will be the container for all necessary components for setting up a code city and all objects representing any kind of information about the code city, such as blocks. Give it a meaningful name. The city object must be tagged by Code City.
The position and scale of this cube will determine the position and scale of the code city that will be generated within this city object. You can place and scale it as you like. For instance, you can put it on a table in your scene. The x and z axis may then be chosen so that it fits on this table. The height (y axis) may be minimal. Remember that one Unity unit corresponds to one meter in reald world. If your city object is a cube, it will also have a mesh renderer and a box collider by default.
The following additional components should be added to this new city object:
- SEE.GO.Plane; this plane handles the culling of the city; objects of the city leaving the city object will be culled by SEE.GO.Plane; choose 1 for the Scale Factor attribute of this component (which should be the default); if you use a Unity object that has a different interpretation of the scale values, as for instance, a Unity plane, you may need to adjust the Scale Factor attribute accordingly so that 1 unit of the scale represents 1 meter in real world (1 scale unit of a plane is actually different from 1 scale unit of a cube).
- DesktopNavigationAction; this component reacts to user input interacting with the code city, such as zooming and moving. It will be used in a desktop environment with 2D display, keyboard, and mouse. Its attribute Portal Plane must be the SEE.GO.Plane component you attached to the city_object.
- XRNavigationAction; this component is analogous to DesktopNavigationAction but reacts to user input from within a virtual reality environment with head-mounted display and VR controllers. Its attribute Portal Plane must be the SEE.GO.Plane component you attached to the city_object.
- An instance of a subclass of AbstractSEECity such as SEECity or SEECityRandom; see below.
If you want to create a city for a graph that you can load from disk (in GXL format), add a component SEECity to the GameObject you just created. The prefix of the path where the GXL file is located can be set as "Data path prefix". There is a "Select" button next to the text field allowing you to choose a directory. The path prefix must end with a directory separator. The name of the GXL file can be entered in the text field labeled by "GXL file". If your GXL file also has a CSV file with metrics you want to import, you can specify its name in the text field labeled "CSV file". The CSV file is optional.
If you want to create a random graph instead, add a component SEECityRandom to your GameObject. You can specify the type of nodes for inner nodes and leafe nodes, the type of edges between either inner nodes or leaf nodes, the number of inner nodes and leaf nodes as well as the respective edge densities. The edge density is a value between 0 and 1 specifying the likelihood of existence of an edge between any pair of nodes. In addition to that, you can determine the names of leaf node attributes and two parameters for creating their values randomly. The two parameters are the mean and standard deviation of a normal distribution from which to draw the values randomly. These parameters allow you to control the metric values. Which of these metrics you want to visualize and how is defined in the section at the top of the inspector of this component as explained in the following.
The code city object where the instance of an AbstractSEECity is attached to as a component defines the position and scale of the generated code city. More precisely, the width along the x axis of the containing game object specifies the width of the generated city. The position of the generated city is the center of the containing game object.
- Width is the leaf node metric attribute (must be numeric) determining the width (x co-ordinate) of the game object created for a leaf node.
- Height is the leaf node metric attribute (must be numeric) determining the height (y co-ordinate) of the game object created for a leaf node.
- Depth is the leaf node metric attribute (must be numeric) determining the depth (z co-ordinate) of the game object created for a leaf node.
- Style is the leaf node metric attribute (must be numeric) determining the style of the game object created for a leaf node. The interpretation of "style" depends upon the kind of visual object you choose for a leaf node. If you select blocks, the style determines a color gradient from white to red. If you choose CScape buildings instead, the style determines the facade of the building.
- Style is the inner node metric attribute (must be numeric) determining the style of the game object created for an inner node. The style determines a color gradient from white to red.
- Leaf nodes determines the kind of visual object to be created for a leaf node. In case of "Blocks", cubes will be used. In case of "Buildings", more realistic CScape buildings will be used instead.
- Inner nodes determines the kind of visual object to be created for an inner node: Blocks (cubes), Rectangles (a line forming a rectangle), Donuts (a circular Donut chart with additional metrics), Circles (a line forming a circle), and Cylinders. If you choose "Empty", no game object will be created for an inner node.
- Node Layout determines the node layout, that is, how the nodes will be positioned in the scene (see below).
- Z-score scaling allows you to have the metric values be normalized by the z-score normalization. This normalization enables you to make direct comparisons between two different types of metrics. Some metrics may have a very large value range and some others only a very narrow small value range. Without normalization the dimensions of the game objects representing leaf nodes, will be very different in such a case. With normalization, the dimensions can be compared to each other. The normalization will also smooth out the values. If you do not select this option, the selected dimension of a node will be a linear interpolation between 0 and the maximal value of the metric selected for this dimension.
- Show erosions allows you to show the number of software erosions as a set of icons above the game object for leaf nodes. The size of those icons is a linear interpolation between 0 and the maximal number of the respective kind of erosion depicted by the icon. The icons are stacked above the game building according their size.
The available node layouts fall into two different categories: (1) flat and (2) hierarchical. Flat layouts do not show the structure of the software, while hierarchical give you insights into the structure.
Flat layouts
You should select "Empty" for inner nodes when you select a flat layout in general because you will likely not want to mix leaves and inner nodes (although you are not forced to do so).
- Manhattan lays out the nodes in as a matrix in alphabetical order of the linknames of the nodes. The matrix has the same number of game objects in each row.
- Flat Rectangle Packing strings the nodes together in a very compact way so as to minimize the space required for the city. The order for placing the nodes is chosen heuristically to achieve this effect: in descending order of the nodes width and depth.
Hierarchical layouts
Hierarchical show the nesting of inner nodes and leaves. There is generally a dependency between a hierarchical layout and the kinds of game objects to be created for inner nodes. For instance, Circles should be used for Balloon and Circle Packing, Blocks for EvoStreets, and Rectangles for TreeMap.
- Circle Packing The hierarchy of the software is depicted as nested circles where the nodes within a circle are put as close together as possible so the the radius of the outer circles is as small as possible. Recommended game object for inner nodes: Circles.
- Balloon The hierarchy of the software is depicted as nested circles where the nodes within a circle are placed on an inner circle. This way the inner part of a circle remains empty. This space can be used for Donut charts. Recommended game objects for inner nodes: Circles or Donuts.
- EvoStreets The hierarchy is shown as branching streets. The top level node is depicted as the widest street. At each deeper level, streets are forked orthogonally with decreasing street width. The leaves are placed along the street they belong to. Recommended game object for inner nodes: Blocks.
- TreeMap The hierarchy is shown as nested rectangles in a very compact given rectangular space. Recommended game object for inner nodes: Rectangles.
- Edge layout allows you to determine how edges should be drawn (see below).
- Edge width defines the width of the lines drawn for edges.
- Edges above blocks determines whether edges are draw above the game objects from roof to roof. If you are not selecting this option, the edges will be drawn underneath the game objects from their grounds to grounds, that is, below the city.
- Bundling tension specifies the tension by which hierarchically bundled edges are attracted. The value must be in the range from 0 to 1, where 0 results in straight edges and 1 in maximally bundled edges. The recommended value is 0.85.
Edge layouts
Similarly to node layouts, there are two different categories of edge layouts: (1) flat and (2) hierarchical. Straight and Spline are flat edge layouts that do not take into account the node hierarchy, whereas edges in the edge layout Bundling are guided by the node hierarchy.
The following edge layouts are available:
- None If selected, edges are not drawn at all.
- Straight Edges are drawn on the shortest path between the game objects they connect as a straight line.
- Spline Edges are drawn on the shortest path between the game objects they connect as a simple spline.
- Bundling Edges are hierarchically bundled. An edge between two nodes, A and B, are drawn along multiple control points with respect to their node hierarchy. The control point of an inner node is located above the center of it in the x/z plane. The y co-ordinate is chosen proportional to the inner node's level in the node hierarchy, where the root node has the highest level. The control points from node A to node B are along their ancestors in the node hierarchy up to their lowest common ancestor. The control points act like cable ties yielding the visual bundling effect of this edge layout.
After configuring the appearance of the city as describe above, press the "Load" button to load a graph from disk. When the graph was loaded successfully, all available node types will be listed. Unselect those you do not want to visualize, then hit the "Draw" button. If you made any changes to the settings, you can hit the "Re-Draw" button to update the visualization. The underlying loaded graph will not be loaded again. If you want to delete the city and the loaded graph, press "Delete". All buttons are locate at the bottom of the configuration dialog.