Improov User Guide

MiddleVR

1 1: What is Improov?

Collaborative design review in VR

Collaborate in the same virtual workspace, no matter where you are. Please take a look at the Improov website for more information: https://www.improovr.com/

2 2: Security information

2.1 2.1: Transferred data

Improov uses the WebSocket Secure communication protocol. We make sure that only the minimum necessary data will be transmitted to the server.

Here is a list of the data that is transferred over the secured network connection:

Here is a list of the data that is collected on the server for Improov to work properly:

Data that are not transmitted:

Data that will be transferred if you use automatic model transmission:

2.2 2.2: Connection encryption

Improov encrypts its connections using the standard TLS (Transport Layer Security) version 1.2 protocol.

We recommend that you use the online meeting server as it uses a verified TLS certificate.

But you can still use the private server. By default, the Improov server generates a temporary certificate and RSA key pair each time it is started, but you can specify a custom certificate and key. See Advanced security setup for more information.

2.3 2.3: Improov meeting password

All connection are made using TLS encryption as explained in the connection encryption section. After this, communication channel is created, we will use a Session ID with a Meeting Server (or a IP Address) to identify the server where the Improov server is started. The first handshake to authenticate the user will use a password to make sure only the wanted collaborators are present on the meeting.

2.4 2.4: Model transmission

Improov provides an Automatic Model Transmission feature to ease the collaboration. It will transfer the imported object hierarchy, materials and tessellated geometry. These information are the most important and must be secured accordingly.

To do so, we will be using a second password. This password will never be transmitted to the server to make sure that only the user and the designed collaborator can open this file. You need to communicate this password to all collaborators before the meeting with the [meeting password]{#security_meeting_password} and the session ID (or server IP address). This does mean that you are responsible to transmit this model password in a secure way, for example by internal company chat, encrypted mail, or any tool that your company generally uses to transfer secure messages.

The model is encrypted on your computer with the password that you provide. The model is then securely sent over the websecure communication channel. It is not stored on our server disk, it is only stored in the memory of the server application. Our online server computer was evaluated by a French cyber security company which concludes that we respect the state of the art security recommandations. Then even if an intruder managed to get access to our secure server computer, he would have to hack our server application to get access to the encrypted data in memory. He would then have to decrypt the data, but this is close to impossible, see below for the details. This also means that even we can’t access your data.

For the nifty details, we use the PBKDF2 algorithm to generate a robust key from a model password. This key is then used by Improov to encrypt data with AES algorithm. The model password is never transferred to our server, even on a hashed form.

As soon as your meeting ends, we delete the data on our server.

We understand that each company has a different security policy. If using an external server is not an option, the private server is of course still working. However, keep in mind that it won’t have the session ID protocol, so you will need to use an IP address in order to connect to your collaborators.

You can also buy a private session ID server that we will install on your own private company network to have the benefits of using the session ID and your own security.

Please get in touch with us if you have any question about our security approach, especially if this does not seem suitable for you.

3 3: Installing Improov

3.1 3.1: Requirements

3.1.1 3.1.1: Operating system

Improov requires a 64-bit version of Windows 7 or later.

Running Improov on Windows 7 requires the Service Pack 2 or later.

3.1.2 3.1.2: Compatible VR systems

Improov uses the MiddleVR for Unity plugin internally, so you can use any VR system supported by it except systems which use a cluster of computers. This includes HMDs such as the Oculus Rift CV1, the HTC Vive or other VR systems such as Powerwalls, etc.

For a comprehensive list of all supported devices, please follow this url : http://www.middlevr.com/doc/current/#requirement_devices

The requirements for 3D monitors, 3D projectors, 3D-TVs, head-mounted displays, passive and active stereoscopy are the same as MiddleVR: http://www.middlevr.com/doc/current/#requirements-for-using-a-3d-monitor-or-3d-projector

Please note that this configuration depends on the complexity of your 3D models. The following recommendations are for a CAD model of medium complexity.

3.1.3.1 3.1.3.1: For Head-Mounted Displays

3.1.3.2 3.1.3.2: For Wall displays

3.2 3.2: Firewall configuration

3.2.1 3.2.1: Online meeting

The default online meeting server port is TCP 443 (IN and OUT).

3.2.2 3.2.2: Private servers

The default port for a private server is TCP 25000 (IN and OUT).

Optional license server : 6200 by default (TCP and UDP)

3.2.3 3.2.3: Proxy

If a proxy server is configured in the system settings, the Improov client will automatically use it to connect to the server. The proxy server must support HTTPS tunneling using the CONNECT method.

3.2.4 3.2.4: MiddleVR

For users of advanced VR systems such as Walls etc, MiddleVR requires the following ports to be opened in the firewall:

4 4: Using Improov

4.1 4.1: Basic usage

4.1.1 4.1.1: Sharing 3D models

Before starting a collaborative meeting, you have to make sure that all participants have access to all the 3D files that will be used during the session.

In Improov, you can do it manually or automatically using the Automatic Model Transmission feature.

The user is advised to use whatever secure method for sharing the model he prefers. Some people simply send the 3D model via e-mail, or through a company specific secured transmission channel.

4.1.1.1 4.1.1.1: Automatic Model Transmission

First you need to fully understand what using model transmission implies on security. Please take a look at the security section when transmitting a model for more information.

This feature has the added benefit that the loading time on the clients will be much faster than if they loaded the model locally.

Creating a meeting and using model transmission is easy: simply activate the option and specify a password for the model. Please make sure you choose a different password than the meeting one as it will weaken your meeting protection.

When connecting to a meeting using model transmission, make sure to specify the model password, otherwise, you will be disconnected with an error: Bad model password.

4.1.1.2 4.1.1.2: Manual Model Transmission

You can choose to transfer the model via your favorite transmission method (mail, dropbox etc). This method is a bit more tedious than Automatic Model Transmission, but you might prefer it to master the security aspects.

4.1.1.2.1 4.1.1.2.1: Loading a file from anywhere on the disk

The organizer can choose to load a 3D model anywhere on its hard drive. For each participants Improov will then try to load this 3D model at this exact same path on every computer.

For example let’s take two distant users, Alex and Zavier.

Alex loads a 3D model located on C:\MyProject1\2018\Iteration1.fbx

On Zavier’s computer, Improov will then try to load this file at the exame same path. If the model is here, Improov will load it.

If Improov cannot find the model, Zavier will be immediately disconnected.

Sometimes for security reasons the users only have access to their user folder C:\Users\<Username>\

So it Alex tries to load C:\Users\Alex\MyProject1\2018\Iteration1.fbx, Zavier’s Improov will try to access this exact same path on its computer, which probably does not exist. Zavier will the be disconnected.

One solution is to use Improov’s Default Path described below.

4.1.1.2.2 4.1.1.2.2: Using the Default path

The Default Path, defined in the Settings, is a path that will be used as a root path for your 3D models repository.

By default the path is set to C:\Users\<your name>\Documents\Improov.

For example let’s take two distant users, Alex and Zavier.

The default path for Alex is: C:\Users\Alex\Documents\Improov.

The default path for Zavier is: C:\Users\Zavier\Documents\Improov.

If the file you are loading is NOT located in this default path or in a child folder, Improov will send the absolute path to all users.

If the file you are loading is located in this default path or in a child folder, Improov will send the path of the model relative to the default path to all users.

Suppose Alex imports a file located at : C:\Users\Alex\Documents\Improov\BigProject\Box.3dxml.

Improov will take the path of the model relative to the Default Path, in this case BigProject\Box.3dxml, and send that to all users. All users will then load this model relative to their default path.

Zavier will then load C:\Users\Zavier\Documents\Improov\BigProject\Box.3dxml.

Note: If a client cannot locate the file at the given path, he will be disconnected. He can fix this problem by putting the 3D model in the correct folder and reconnect.

4.1.2 4.1.2: Getting started window

The first thing you will see when opening Improov is the getting started window:

This window will help you to quickly get into your work.

4.1.2.1 4.1.2.1: Join or Create an online meeting

An online meeting is a session created on a online public meeting server. This solution is made to simplify the collaboration process. You don’t need to think about the IP address or make sure that everyone is on the same local network as with the private server.

You only need to ensure that each client can reach the server (by default https://session.improovr.com:443). Please make sure to read how we use your data and where it will be transmitted

If everything is working, you just need to add a password and you can Create a meeting with a desktop or in VR directly (this option work only with HMDs).

To join a meeting you will need the Session ID which can be found in the collaboration panel. You can join with a desktop or in VR directly (this option work only with HMDs).

Note: If the creator of an online meeting quits the meeting, everybody will be disconnected

Note: If the creator of an online meeting is disconnected non-willingly (either due to a network connection error, a crash or anything else), he has 5 mins to reconnect to the meeting using the original Session ID. If the creator of the meeting is not back in the meeting within 5 mins, the meeting will be closed and everyone will be disconnected.

4.1.2.2 4.1.2.2: Join or Create a private server

A private server is an Improov server that can only be accessed on the same local network using the local network address. This ensures that you manage all aspects of the security by your own standards.

To join a private server you will have to use local network address of the server.

To create a private server you only need to set a password, and then create the server and autoconnect with a desktop or in VR directly (this option works only with HMDs). You can use the Copy parameters button to put the server information (address and password) in your clipboard so that you can share it outside of the application.

To join a private server you need to set the network address of the host server and the password. You can join with a desktop or in VR directly (this option works only with HMDs).

4.1.2.3 4.1.2.3: Standalone private server

You can also setup a private Improov server on a computer that will not be used as a client. For example the server could be setup on an online computer accessible by all your users. You will need a custom license to run it. Please contact the support.

4.1.3 4.1.3: Desktop application main window

After joining or creating a private server or an online meeting, you will see the desktop interface.

The Improov desktop GUI is made of multiple panels:

The desktop main window can be resize like every other application but the panel will not be reduced.

4.1.4 4.1.4: Importing a file

Note: Make sure to check section Sharing 3D models.

To start working on your model, you first need to import it. You will find the import function in the file menu:

To import a model in Improov you need to use the import window:

You can import two type of models in Improov:

For more information about importing environment, please look at the section importing environment

To import a model use the square button next to the text field to select a file:

After selecting a file and click open, you will be back in the improov panel with the selected file path in the text field.

Below the file field, you can specify options like translation, rotation and import unit. For more information, please look at the section import advanced options.

Note that these options will be stored automatically and re-applied on the next model import.

By clicking Import, you will then import the file in Improov.

Navigation is the set of methods used by the user to move around the virtual environment. They are based on the navigation methods of popular 3d engines. The default navigation is Mouse Sketchup.

Method Name Action Command
CATIA Translation Middle Mouse Button + mouse movement
CATIA Rotation Middle Mouse Button + Left Mouse Button + mouse movement
CATIA Zoom Middle Mouse Button + Click Left Mouse Button + mouse movement
Solidworks Translation Ctrl + Middle Mouse Button + mouse movement
Solidworks Rotation Middle Mouse Button + mouse movement
Solidworks Rotate the horizon Alt +Middle Mouse Button + mouse movement
Solidworks Zoom Mouse Scrollwheel
Solidworks Slow Zoom Shift + Mouse Scrollwheel + mouse movement
Mouse Sketchup Translation Shift + mouse movement
Mouse Sketchup Rotation Middle Mouse Button + mouse movement
Mouse Sketchup Zoom Mouse Scrollwheel
Walk Sketchup Slow horizontal translation Right Mouse Button + mouse movement
Walk Sketchup Fast horizontal translation Ctrl + Right Mouse Button + mouse movement
Walk Sketchup Slow translation in camera plane Shift + Right Mouse Button + mouse movement
Walk Sketchup Fast translation in camera plane Shift + Ctrl + Right Mouse Button + mouse movement
Walk Sketchup Rotation Middle Mouse Button + mouse movement
Walk Sketchup Zoom Mouse Scrollwheel

4.1.6 4.1.6: Interact in the 3D view

Selection allows you to specify one or more object that can be acted upon with other tools or inspected with the inspector window. Selected objects cannot be selected by other users.

An object can be selected by :

Now that the model has been imported, there are various ways to interact with it :

4.1.7 4.1.7: Collaborate with users

You can use the users panel to manage other users in the scene:

4.1.8 4.1.8: Voice chat

Improov comes with an embedded voice chat. By default the voice chat is activated and you are unmuted. You can choose to mute yourself when creating or connecting to an Improov meeting by checking the “Microphone” checkbox.

You can choose to disable the voice chat in the configuration file. This is useful for system administrators who want to implement a company policy to force users to use another way to communicate.

You have multiple information and actions possible in the user panel for the voice chat: - Disable your microphone or the one of each collaborator using the button with a microphone icon on it. - Disable sound on your computer with the second button. - See how loud each user is talking.

If the icons are disabled, the voice server is disabled in the configuration file](#configsettings).

You can also change some more advanced option and select the correct microphone in the settings

4.2 4.2: Using Improov with an HMD

The navigation techniques are based on the following concepts:

By default, the navigation axis is the joystick/touchpad and the navigation button is the wand button 1. For your custom MiddleVR configurations, you can map your chosen device button to the wand button 1 to make it the navigation button.

Below you will find a list of the various navigation techniques at your disposal:

Methods Description
Teleport Use a projected ray to teleport yourself to far and close places alike.
Fly Use the navigation axis to navigate in the direction pointed by the controller.
Elastic Stretch a virtual elastic in the direction you want to move to. The more you stretch, the faster you move.

4.2.1.1 4.2.1.1: Teleport Navigation Method

4.2.1.1.1 4.2.1.1.1: Button mapping

Below you will find the standard controllers mapping for the teleport navigation method :

4.2.1.1.2 4.2.1.1.2: How to use it

4.2.1.2 4.2.1.2: Fly Navigation Method

4.2.1.2.1 4.2.1.2.1: Mapping

Below you will find the standard controllers mapping for the fly navigation method :

4.2.1.2.2 4.2.1.2.2: How to use it

You will move in the direction pointed by the controller.

For example, if you want to strafe, point your hand to the right or to the left and press up.

4.2.1.3 4.2.1.3: Elastic Navigation Method

4.2.1.3.1 4.2.1.3.1: Mapping

Below you will find the standard controllers mapping for the elastic navigation method :

4.2.1.3.2 4.2.1.3.2: How to use it

Enabling the elastic will display the red line shown above, allowing you to stretch it in the direction you want. The more the elastic is stretched, the faster the navigation is. The same concept applies to rotation.

4.2.2 4.2.2: The hand

The hand is the main interaction tool for a cross-platform VR. Whether a client uses a HMD or another system, the wand will still be an efficient and natural interface.

It is represented by a hand with a colored ray. The ray’s color is linked to the user’s identity.

In MiddleVR, a wand is a set of virtual buttons and axis. Each hardware has its own mapping to the wand. In Improov, only three buttons and one axis are used : the interaction button, the navigation button, the menu button and the navigation axis.

Button Function
Interaction button It is the main button used for interacting with the 3D environment and the GUI.
Navigation button This button is used by some navigation techniques.
Menu button This button spawns the floating menu in front of the wand.
Navigation axis It is used by some of the navigation techniques to have a direction to apply to the user.

In VR, the user can freely manipulate objects. By selecting an object and maintaining the trigger, the user can move the object around freely. The user can also navigate while holding the object. Collisions between objects may be highlighted and prevented.

4.2.3 4.2.3: Selection

To select and object, you have to point it with your wand and press the interaction button.

The tool’s interface is similar to the desktop application. For more details, please refer to the appropriate section.

4.2.4 4.2.4: Immersive menu

The immersive Improov GUI is identical to the desktop GUI. However, the behaviors are different for some tools.

The top of the menu contains the date, information about the user’ and host’ IPs and a window resizing button.

The immersive menu is bound to the user. During navigation, it follows him. You can move around the menu by grabbing the top part and dragging it. You can also use the menu button to spawn the GUI in front of the wand. This part of the GUI contains :

The menu is made of 3 tabs : Home, Tools and Scene. They are displayed on the bottom of the menu. The fourth button is a shortcut to the Undo function.

5 5: Tools

5.1 5.1: Selection

Selection is the default tool in Improov. You can use this tool in the 3D view to select an object part or multiple parts.

All buttons can be found in the edit menu. Some help about the current selection is displayed in the console and in the Selected object count field in the Selection panel.

5.1.1 5.1.1: Selection actions

Button Action
Select All Will select every nodes* of the scene (Can be quicly made using the Ctrl + A shortcut).
Deselect All Will clear the current selection.
Select parents Will select every direct parent of all current select object.
Select children Will select from the current node all children node and will discard every other intermediate*.
Invert selection Will invert the current selection without all children of the selected object*.
Select All Select all node in the scene.

* For more information about node and parenting rules, please look at the scene graph differences from CAD section

5.1.2 5.1.2: Visibility actions

Button Action
Show all Show all hidden objects.
Show selection Show the selected object and all it’s children*.
Hide selection Hide the selected object and all it’s children*.
Show only selection Show only the selected object and all it’s children and hide everything else.
Reframe selection Will change the desktop camera position to make sure the object is visible directly in front of the camera.

* For more information about node and parenting rules, please look at the scene graph differences from CAD section

5.1.3 5.1.3: Scene graph differences from CAD

In most CAD software, you will find the same definitions and words to describe a 3D scene:

Improov translates this CAD product tree in another hierarchy based on a tree of 3D nodes. This mean that every intermediate assembly, part or body will have a local transform and a parent with the same properties:

5.1.4 5.1.4: Direct and indirect selection

Because we have a node representation, we have a notion of direct and indirect selection.

A node is directly selected if you have clicked on its 3D representation in the 3D view or if you have clicked on it in the hierarchy.

When a node is directly selected, its color is changed to match the color of the user who selected it. When the node is deselected, the color is reverted back to the parts original color.

If you select directly a node that has children, all its children will be indirectly selected. Nodes that are selected indirectly are not highlighted in the same way: only their outline is highlighted. Since parent nodes don’t have a 3d representation, indirect selection is used to represent nodes that will be affected by the Manipulation tool.

If you move a parent node, all the children node will move like this node.

Only the properties of directly selected nodes will be modified in the Properties view.

5.1.5 5.1.5: Multiselection

Selecting multiple object in the Desktop can be made using the Ctrl key. Keep the key pressed until you’ve selected all the desired objects.

Selecting multiple object in VR can be activated with the checkox in the selection tool panel. You then add to the current selection all object you will designated until you click on an empty spce.

The multiselection can be done on the hierarchy and the result will be displayed in the properties panel. All shared field will have the shared value. If this is not the same value, each field will displayed a replacement value :

Every action done in the properties of a multiselection will be made on every selected object. Be careful when editing multiple object at the same time !

The bounding box field will display the bounding box size of all the object it they where inside of a virtual box in the scene. This can be useful to know if all object are close to each other or not.

5.2 5.2: Manipulation

5.2.1 5.2.1: Transformation tool

The transformation tool enables you to change the position and orientation of a selection or multiselection of nodes.

You can use the gizmos displayed in the 3D view or use the menu panel to be more precise.

5.2.2 5.2.2: Stretch tool

The Stretching tool is used to deform an object.

The widget is made up of 9 parts:

Component Function
Red arrows Scale object along the X axis
Green arrows Scale object along the Y axis
Blue arrows Scale object along the Z axis
Red line Measure the object along the X axis
Blue line Measure the object along the Y axis
Green line Measure the object along the Z axis

In the desktop Improov application, the widget size is adjusted so that it is always the same size on screen, regardless of the distance from the user.

Note: Only one mesh can be scaled at a time. Only a node that has a visual representation can be scaled. This means only leaf nodes, not parent nodes, can be stretched

5.3 5.3: Measure

The Measure tool draws a ruler between two points in space and displays its length.

A measure is made up of two points attached to objects and a vector between them. By default, it displays only the distance (in meters) between these two points. If any of the objects moves, the measure will be updated. If one of them is hidden, the measure will be hidden too.

Several functions are available for this tool :

Button Function
Decomposition Show the decomposition along the XYZ axis for all the measures. Disabled by default.
Show Display or hide all existing measures.
Clear Erase all measures.

The axis decomposition of a measure generates 3 similar-looking colored lines. The red line represents the measurement value on the X axis. The green line is on the Y axis and the blue line is on Z.

5.4 5.4: Point of Interest

This tool allows the user to provide a visual/audio feedback to all the other users on a particular element by clicking on it.

You have two type of POI :

5.5 5.5: Cutting plane

The Cutting plane tool allows the user to spawn up to 3 section planes. A section plane cuts all the meshes in the positive Y direction. All meshes with the Slice property enabled will be cut.

While using the tool, a mockup of a section plane is spawned in front of the mouse pointer. If any object is close by, the plane will be located on the object. The plane colors are, in order, red, green and blue. These colors are applied to the section of the meshes.

Clicking will spawn a section plane on the desired location. Then the user will be required to select the orientation of its Y axis. By moving the pointer around the plane, the user will be able to turn it adequately. The plane’s normal orientation is by default constrained to 6 directions (X,-X,Y,-Y,Z,-Z) but it can be tweaked by selecting the plane afterward and rotating it manually.

5.6 5.6: Drawing

The Drawing tool allows the user to make drawings in the 3D environment.

5.6.1 5.6.1: Pen

Each drawing is colored by the user’s own color and shared with all the other users.

The tool is used by maintaining the left mouse button while moving the pointer. The drawing will appear at a constant distance from the user.

Existing drawings can be cleaned by clicking the button Clear.

5.6.2 5.6.2: Extrusion

This tool can be used to make 3D shapes. It is used by left clicking in the scene to create the shape point by point.

Options are available such as “Draw on objects” and “Draw on floor”.

It is possible to cancel the extrusion, or to remove the last point, by left clicking on their respective buttons.

5.7 5.7: Screenshot

The screenshot tool is useful to memorize elements or modifications of the environment by taking pictures of it. Pushing the button Take Picture will take a picture of the actual user’s view.

It is possible to specify the location in which the screenshosts are exported. Each image will be named following the pattern : Improov_Screenshots_sessiondate_time/1.jpg. The number will be incremented for each screenshot in the session.

6 6: Settings

6.1 6.1: Improov settings

The Improov settings are all the application options that can be changed at runtime. The settings are stored in the user local folder (“C:\Users\[user]\AppData\Roaming\IMPROOV\user_settings.toml” or “%appdata%\IMPROOV\user_settings.toml”). If you are in a company using Enterprise Windows, this settings file will be shared between all the computer you will be log in. The settings window can be opened by clicking File/Settings.

Keep in mind that you need to click “Apply” after modifying a settings, or else no settings will be modified. The reset settings button will reset all settings to their default values.

6.1.1 6.1.1: User settings

Setting Explanation Default
User Name User name that will be displayed above your avatar and in the user list DefaultUser
User Color Selected objects will use your color as overlay Red
User Avatar Type of the user avatar
Language The language used in Improov. Available: English, Japanese, Chinese English US
Navigation method The method used for user navigation in the scene. See also Navigate MouseSketchUp (Desktop) and Teleport (Immersive)
Keep on floor Toggle this to lock the user on the floor. The floor is auto-detected by Improov No
Lock altitude Toggle this to prevent the user from moving up and down No
Background color Change the background color in the scene Light gray
Display unit Change the unit. Default unit is meter. Available: km, m, dm, cm, mm, mi, yd, ft, in Meter
Line thickness Change the thickness of lines. Expressed in number of pixels on screen 2 pixels

6.1.2 6.1.2: Network settings

Setting Explanation Default
Server address The address of the meeting server. See also Create or join meeting session.improovr.com:443
Connection status Display the status of the connection to the meeting server /
Test connection Use this button to test the connection to the meeting server /
Local IP Display your local IP. This cannot be changed /

6.1.3 6.1.3: Voice settings

Setting Explanation Default
Use voice chat If checked, use the embedded voice chat. See also Voice chat No
Always mute at start If checked, will mute voice chat when starting Improov. Note that you will still join the voice chat, and still be able to hear other users. You will need to manually activate your microphone No
Driver microphone If you have multiple microphones plugged in your computer, select here the one that will be used. The default value will select the default microphone in the Windows settings default
Microphone volume Check this volume bar to test your microphone volume /
Sound volume test Click this button to play a test sound /

6.2 6.2: Improov configuration file

The Improov configuration file contains the startup configuration options that can be changed only before starting any instance of Improov. It is stored next to the Improov installation directory (in a standard application “C:\Program Files\Improov\bin\Improov.toml”). By default, this file doesn’t exists as we start Improov with the default parameters, but if you want to add specific options, just add a text file with the following content:

[Log]
LogLevel = "INFO"
LogFileName = "Improov"
LogPath = ""

[Net]
DisableTLS = False
ServerAddress = "localhost"
ServerPort = 25000
StartFlags = "NOT_CONNECTED"
AlwaysTrustCertificate = False
EnableVoiceChatOnServer = True

[Import]
OutputDirectory = ""

[Tool]
ManikinTextureFile = ""

[Render]
DrawCallOptim = True
Setting Explanation Default
LogLevel Change information display in the log file. Be careful, if you increase the log level you will decrease the overall application performance. (SYSTEM = 0, ERROR = 1, WARNING = 2, INFO = 3, DEBUG = 4) “INFO”
LogFileName Filename of the log file. If you start a server or an immersive player, the logfilename will be filename + _Server or _Immersive “Improov”
LogPath Path directory of the log file. If the path is empty or invalid, the log file will be stored in it’s default location. “”
DisableTLS This option is made if you want to deactivate the network security encryption. Be careful, all Improov message will be readable from the Network. False
ServerAddress The default server address to connect to if you change the StartFlags to AUTOCONNECT. “localhost”
ServerPort The default server port to connect to if you change the StartFlags to AUTOCONNECT. 25000
StartFlags Starting flag can be “AUTOCONNECT” to automatically connect to the specified server, “CREATE_LOCAL” to automatically create and connect to a local Improov Server, “NOT_CONNECTED” to have the default getting started. “NOT_CONNECTED”
AlwaysTrustCertificate Change this option if the Improov server you are connecting to doesn’t have any certificate. False
EnableVoiceChatOnServer Enable or disable voice chat of all meeting or local server you will create. True
OutputDirectory This is the default directory where all screenshots and scene will be saved by default. “”
ManikinTextureFile If you want to have a customized Manikin texture, please specified the absolute path here. “”
DrawCallOptim Use or not the rendering optimisation in Improov. True

6.3 6.3: Cache file

Improov will store some persistent data in this file. There should be no reason to modify it. Cache: “C:\Users\[user]\AppData\Local\MiddleVR\cache.toml”.

7 7: License

7.1 7.1: Improov editions

Improov comes in different editions. Please look at the website for more information about each edition limitations.

7.2 7.2: License management

This is what the license management window looks like:

You have several choices:

  1. Activate a license.
  2. Use a license server license server.
  3. Close the current wizard and do not modify anything.

7.3 7.3: Local installation

If you already have a license key for this computer, please select Activate license....

In the Key text entry please paste or write your license key, then press Activate. If the activation succeeded, the window will close and you can start using Improov. If the installation failed, please use check the manual activation section.

7.3.1 7.3.1: Manual activation

Click on “Website activation”.

If your computer has an internet access, enter you activation code then click “Go to website”. If not, use an another computer that has internet access and go to the License Activation Center (http://license.middlevr.com):

After entering the activation code in the Improov “Website Activation” dialog or directly on the website, you should arrive on this page:

Now enter the HostID values on the website. Note: Please enter the entire HostID text after the “=” character, including the trailing dot character if there is one.

Click the “Activate” button on the website, then when the license activation has finished, click the “Download” button to download your license file. Transfer the license file to the computer running Improov you used a different computer.

In Improov, click on “Load license” and select your license file.

7.4 7.4: License server installation

7.4.0.1 7.4.0.1: License server

The following steps describe how to easily install a license server on Windows using the LM-X End-user Tools (Windows only).

  1. Run Program files/Improov/bin/licensing/lmx-enduser-tools_v4.9.8_win64_x64.msi.

  2. During the installation process, make sure that “Install LM-X server” is checked.

    Browse to find our liblmxvendor.dll in the Improov installation path /bin/licensing.

    Keep “Install LM-X license server as a service” checked.

After the installation, open the configuration file lmx-serv.cfg from the LM-X tool installation folder (for example “C:\Program Files\ X-Formation\LM-X End-user Tools 4.8.13 x64\-serv.cfg”).

Set the value LICENSE_FILE to the path leading to your floating/network license file.

You can choose your TCP_LISTEN_PORT if needed.

Make sure to open this port (TCP and UDP) in your firewall, both on the license server machine and the client machines.

If there are any problems running the license server, the log file will indicate the cause of the problem. You can find the log file at the path indicated in the configuration file value LOG_FILE. If still not found, check to make sure that the path is correct.

Note: when upgrading Improov you must upgrade the version of LM-X if it has changed!

7.4.1 7.4.1: Activating a floating license for your license server

After installing the LM-X End-user Tools and the license server, run the LM-X Configuration Tool.

7.4.1.1 7.4.1.1: Configuring clients

On the client machines, you can either:

8 8: Advanced usage

8.1 8.1: Import advanced options

8.1.1 8.1.1: Models format information

8.1.1.1 8.1.1.1: Standard input file format

Format Description Supported version
.3dxml format 3dxml en ascii /
.gltf GL Transmission Format Versions 1.0 and 2.0
.glb GL Binary Versions 1.0 and 2.0
.dae ISO 17506 Collada/Dae : COLLAborative Design Activity /
.obj OBJect file /
.stl STereoLithography made by 3D Systems /
.ifc Industry Fundation Classes /
.fbx FilmBoX Autodesk Versions 2013 to 2016
.igs ASME Y14.26M IGES : Initial Graphics Exchange Specification Versions 5.2 and 5.3
.step, .stp, .p21 ISO 10303-21 STEP : Standard For the Exchange of Product model data Versions 203/214/242

8.1.1.2 8.1.1.2: Native CAD file format

Format Description Supported version
.CATPart CATIA V5: CATia file PART Versions R10 to R26
.CATProduct CATIA V5: CATia file PRODUCT Versions R10 to R26
.3dxml CATIA V6: format 3dxml en binaire Versions 2011X to 2013X
.sldprt SoLiDworks PaRT file Versions 1999 to 2018
.sldasm SoLiDworks ASseMblage Versions 1999 to 2018
.jt Siemens NX: Jupiter Tessellation Versions 7.0 to 10.2
.prt., .prt|PTC Creo: Pro/Engineer part files|Versions 13 to Creo 4| |.asm., .asm PTC Creo: Pro/Engineer assembly files Versions 13 to Creo 4
.ipt Inventor part files Version all to 2017
.iam Inventor assembly files Version all to 2017

8.1.2 8.1.2: Importing Environment

8.1.2.1 8.1.2.1: Advanced options

Field name Effect
File path Specify the path of the environment you want to import.
Translation Apply the given translation to the environment after it has been imported.
Rotation Apply the given rotation to the environment after it has been imported.
Scale factor Apply the given scale factor to the environment after it has been imported.

8.2 8.2: Virtual mannequin

8.2.1 8.2.1: Setup mannequin

8.2.1.1 8.2.1.1: MiddleVR Config

You need to make a MiddleVR configuration that will have the same number of nodes as the number of tracked points by your system. For example, if you have the following DTrack nodes:

You will need to make a MiddleVR configuration including 4 nodes like this (names can be whatever you want, same as the DTrack nodes or not):

Be sure to save this configuration file in a folder that you will remember (it will be needed later).

8.2.1.2 8.2.1.2: Targets.xml

This file is used to link nodes from the MiddleVR configuration to body parts before sending information to IPSI (default location : C:/Program Files/MiddleVR/Improov/bin/targets.xml). It contains three different types of data:

Guidelines to modify the file:

About custom ids:

Let’s say that you want to use the following MiddleVR configuration nodes:

Then you have to:

Here is an example of the properly setup file:

[...]
    <Targets>
        <Target>
            <m_name>Hips</m_name>
            <m_id>-1</m_id>
            <m_weight>10.0</m_weight>
        </Target>
        <Target>
            <m_name>LeftUpperLeg</m_name>
            <m_id>-1</m_id>
            <m_weight>1</m_weight>
        </Target>
        <Target>
            <m_name>RightUpperLeg</m_name>
            <m_id>-1</m_id>
            <m_weight>1</m_weight>
        </Target>
        <Target>
            <m_name>LeftLowerLeg</m_name>
            <m_id>-1</m_id>
            <m_weight>-1.0</m_weight>
        </Target>
        <Target>
            <m_name>RightLowerLeg</m_name>
            <m_id>-1</m_id>
            <m_weight>-1.0</m_weight>
        </Target>
        <Target>
            <m_name>LeftAnkle</m_name>
            <m_id>-1</m_id>
            <m_weight>3.0</m_weight>
        </Target>
        <Target>
            <m_name>RightAnkle</m_name>
            <m_id>-1</m_id>
            <m_weight>3.0</m_weight>
        </Target>
        <Target>
            <m_name>Neck</m_name>
            <m_id>0</m_id>
            <m_weight>2.0</m_weight>
        </Target>
        <Target>
            <m_name>LeftUpperArm</m_name>
            <m_id>-1</m_id>
            <m_weight>2.0</m_weight>
        </Target>
        <Target>
            <m_name>RightUpperArm</m_name>
            <m_id>-1</m_id>
            <m_weight>2.0</m_weight>
        </Target>
        <Target>
            <m_name>LeftLowerArm</m_name>
            <m_id>-1</m_id>
            <m_weight>-1.0</m_weight>
        </Target>
        <Target>
            <m_name>RightLowerArm</m_name>
            <m_id>-1</m_id>
            <m_weight>-1.0</m_weight>
        </Target>
        <Target>
            <m_name>LeftHand</m_name>
            <m_id>-1</m_id>
            <m_weight>20.0</m_weight>
        </Target>
        <Target>
            <m_name>RightHand</m_name>
            <m_id>1</m_id>
            <m_weight>20.0</m_weight>
        </Target>
        <Target>
            <m_name>LeftToes</m_name>
            <m_id>-1</m_id>
            <m_weight>-1.0</m_weight>
        </Target>
        <Target>
            <m_name>RightToes</m_name>
            <m_id>-1</m_id>
            <m_weight>-1.0</m_weight>
        </Target>
        <Target>
            <m_name>RightShoulder</m_name>
            <m_id>-1</m_id>
            <m_weight>1.0</m_weight>
        </Target>
        <Target>
            <m_name>LeftShoulder</m_name>
            <m_id>-1</m_id>
            <m_weight>1.0</m_weight>
        </Target>
        <Target>
            <m_name>Lumbar1</m_name>
            <m_id>-1</m_id>
            <m_weight>1.0</m_weight>
        </Target>
    </Targets>
    <m_manipulationDeviceId>1</m_manipulationDeviceId>
    <FakeTargets>
        <FakeTarget>
            <m_name>HeadNode</m_name>
            <m_id>0</m_id>
        </FakeTarget>
        <FakeTarget>
            <m_name>HandNode</m_name>
            <m_id>1</m_id>
        </FakeTarget>
    </FakeTargets>
[...]

8.2.1.3 8.2.1.3: Improov

Once you are done with the previous steps, you can go back to Improov and start a first person simulation. Check the dedicated section ‘User avatar’ to use it.

8.2.2 8.2.2: RULA Ergonomics

IMPROOV allows to perform ergonomics assessments on virtual humans (see section Advanced Simulation for an insight into virtual humans). Ergonomics assessments are based on the RULA (Rapid Upper Limb Assessment) method, and may be performed in real time to help identifying ergonomics issues and optimizing the work place. Assessments results may be visualized as colored limbs on the virtual human, for a quick overview, or as grades for a more in-depth analysis.

To perform an ergonomics assessment:

  1. Insert virtual humans. This can be the user avatar and/or articulated mannequins.

  2. On any connected desktop client, activate ergonomics assessment tool through Menu > Ergonomics > RULA

  3. On the newly open RULA window, click on Active.

  4. Then click on Pick mannequin, and click on the desired virtual human.

  5. The mannequin limbs are coloured from green (good posture) to red (bad posture), and grades are displayed in the ergonomics assessment window.

Figure 1: RULA user interface
Figure 1: RULA user interface

For a more in-depth analysis, click on the Save posture button to take a snapshot of the posture of the virtual human. A new window opens, where context information may be entered. Once completed, click on the OK button.

Saved postures may be edited by clicking the Edit posture button. Navigate through postures with the < and > buttons.

Saved postures may be exported in Excel 2010 (.xlsx) format by clicking on the Save to Excel button and specifying a file in the files browser.

Figure 2: RULA detailed window
Figure 2: RULA detailed window

8.3 8.3: Commands

Commands are actions which are sent to the server. The list of all the commands executed by all the users during a meeting is called the Command stack of the scene. When a user connects to the server, all of these commands are applied locally.

They can be stored in scene files, shared among other users and some of these can be undone.

A stored command means that it will endure after loading the scene again or after connection. Temporary commands (such as pointing) are not stored. All commands which have a lasting effect on the scene’s state are stored.

A shared command has effects which impacts all users, such as loading a 3D model. Saving the scene is not a shared command.

An undoable command has effects which can be reverted. For example renaming an object can be undone.

Here is a summary of the actions that can be made in Improov:

Command Undoable Shared Stored
Importing a model No Yes Yes
Deleting an object No Yes Yes
Selecting an object No Yes No
Saving a scene No No No
Loading a scene No No No
Translating or scaling an object Yes Yes Yes
Modifying a property Yes Yes Yes
Drawing Yes Yes Yes
Clearing the drawings No Yes Yes
Making extrusion Yes Yes Yes
Clearing extrusion No Yes Yes
Removing last extrusion point No No Yes
Making a measure Yes Yes Yes
Clearing the measures No Yes Yes
Showing the measures No No No
Displaying the axis decomposition of a measure No No No
Taking a picture No No No
Pinpoint No Yes No
Creating a section plane No Yes Yes
Modifying viewpoint No No No
Connecting to a server No Yes Yes
Disconnecting from a server No Yes Yes
Managing the GUI No No No
Changing a widget’s reference axis No No No
Changing anything in the settings No No No

8.4 8.4: Logs levels

Recognized loglevels are:

SYSTEM
Only messages describing the actions taken in Improov (such as connection/disconnection or notifications present in the console) are stored.
ERROR
Error messages are also included in the logs.
WARNING
Notifications about potential problems will be stored in the logs.
INFO
Details about the low-level behavior of Improov (such as message exchange, visible in the server console) will be stored.
DEBUG
Every notification will be stored.

9 9: Advanced - Starting Improov

Once installed you can start Improov via different methods.

9.1 9.1: Basic methods

9.2 9.2: Advanced methods

9.2.1 9.2.1: Starting Improov with command line arguments

Improov will be installed in the Program Files/Improov folder (%programfiles%/Improov). The Improov executable and all the tools shipped with it can be found in the folder Program Files/Improov/bin folder (%programfiles%/Improov/bin).

You can run improov.exe to start Improov in different modes and with different parameters.

Command line Description
-batchmode Removes rendering and input from the Improov instance. Required for standalone servers.
--config configuration_file_path Specifies a custom configuration file to use in Improov. This will automatically set the client as immersive.
--imp-host= address Sets an IP address which holds the standalone server the client must connect to. When given this argument, the client will automatically try to connect to this external server. If it fails, it will open the getting started.
--imp-lmx-server-host=port@ip Sets the IP and port at which to find a license server. By default the ip@port is 127.0.0.1@6200. This is only required if you are using floating licenses and have not specified this address in your environment variables. This argument will be transmitted to any local standalone server spawned.
--imp-logfile=filename Sets a name for the logfile. Logs are stored in %tmp%/MiddleVR/. By default, the log file is “Improov_client.log”.
--imp-loglevel=loglevel Specifies the level of importance of the logs stored in the logfile.
--imp-password=password Sets a custom password. This password is used when connecting to an external server. By default the password used comes from the user preferences. Note: Since any process can see the active processes with their command-line arguments, please be careful when transmitting passwords manually. When launched, Improov will encrypt the password when transmitting to other instances it creates.
--imp-port=port Sets a custom port. This port is used to send data to the server. It is also the port used by any local server created by this instance of Improov to receive data. By default this port is 25000 but can be modified in the user preferences.
--imp-instance=instance Sets the type of Improov. This can be set to Server for a standalone server mode, Desktop for Improov desktop, or Immersive for the immersive mode
--imp-remote The Improov client will not start a local server and will simply open up the connection popup.
-nographics Stop Improov from initializing graphical devices. Required for standalone servers.

The file Improov - desktop.bat includes all the command line parameters, feel free to modify it for your usage.

The batch file Improov - server.bat will create a minimized Improov server window. The file contains command line parameters to help you customise a standalone server for your usage.

9.2.2 9.2.2: MiddleVR tools

MiddleVR is the plugin used to run Improov on non-HMD VR systems such as PowerWalls etc.

MiddleVR tools can be found in the folder Program Files/Improov/bin folder (%programfiles%/Improov/bin).

- Run `MiddleVRConfig.exe` to start MiddleVR Configuration from the Improov installation folder.
- Run `MiddleVRDaemon.exe` to start the MiddleVR Daemon.

For more information see the MiddleVR documentation: https://www.middlevr.com/doc/middlevr-for-unity/current/

10 10: Advanced installation - IPSI

Installation of the given .exe has to be made in the following order:

This version of the server is absolutely mandatory, any other would crash when used with Improov.

10.1 10.1: Saving your IPSI license

The license we sent you should be saved in a folder you remember (this information will be needed later).

10.2 10.2: IPSI Device Configurator

Now that IPSI is installed and the license saved, we need to setup IPSI for it to be able to communicate with Improov:

We need to create a new device with the following information:

It is important to check that the port 5001 is not used by any other application on your system, otherwise IPSI will not be able to communicate with Improov. Before pursuing, check that your device settings look like the following ones:

Press ‘Add’, you should get a result looking like the following picture :

10.3 10.3: IPSI License registration in Improov

You will see a virtual human appear in Improov, meaning that you have successfully activated your IPSI License and Server. The next time you start Improov these functions will be immediately available.

11 11: Advanced installation

11.1 11.1: Information needed for installation

11.2 11.2: Firewall and administrator right

11.3 11.3: Installation on site

For a complete installation, you need to validate multiple steps in the correct order:

11.4 11.4: Avanced security setup

11.5 11.5: Background

Improov encrypts its connections using the standard TLS (Transport Layer Security) version 1.2 protocol.

By default, when launching an Improov server in private server mode, it generates a temporary certificate and RSA key pair each time it is started, but you can specify a custom certificate and key.

Note: When connecting to a private server, Improov does not verify the server identity and only uses TLS for encryption purposes.

11.6 11.6: Installing a custom certificate and key pair

You will have to put the two following files, in the OpenSSL PEM format, into the bin\server folder of your Improov installation path: - cert.pem: the server certificate, - key.pem: the associated key.

Here is an example of generating a self-signed certificate and RSA key pair using OpenSSL on the windows command-line (We provide an OpenSSL executable in the folder bin\openssl of your Improov installation path):

openssl req -config openssl.cnf -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 10000 -out cert.pem