VISSIM® 3DS MAX®

Script
User Guide
Intro
This script is created to import the VISSIM animation from ANI.TXT files to 3DS MAX. A successful
animation import depends on three items.

1. Correct settings and modelling in VISSIM.

2. Creating 3D models for the VISSIM 3DS script.
3. Correct settings in the VISSIM 3DS MAX panel.

This user guide describes these items.

All necessary scripts, 3D models and Tutorials can be found in <VISSIM installation
directory>\API\3dsMaxExport.
1. Modelling in VISSIM
To create a suitable network model for 3DS MAX in VISSIM these items should be adjusted correctly.

1. 3D models and colour distributions.

2. Network details.
3. Simulation parameters.
4. Animations start time and length.

1.1 3D models and colour distribution

Two properties of the VISSIM 3D models are important for the animation; the 3D model’s name and
dimensions.
The 3D model’s name is used by the script to find a proper 3D model as a max file to use for a vehicle or
pedestrian. Therefore for each 3D model from VISSIM’s vehicle 3D model distribution, a 3DS MAX model
should be created. If you want to use your own fleet, the best way is to convert them to V3D files for
VISSIM. If this is not possible, an existing VISSIM 3D model (V3D file) can be renamed and used instead of
the missing model. But the 2D dimensions in the VISSIM model have to be adjusted to have the same
vehicle length. (For more information refer to the “3D Model Distribution” section in VISSIM User
Manual)
The model dimensions are very important for the simulation and the imported animation. If the vehicle’s
3DS MAX model is smaller or larger than the model in VISSIM, the vehicles may overlap or may be too far
apart in the imported animation in 3DS MAX.
The vehicle colours from VISSIM can be used to colour the vehicle in 3DS MAX. To define or adjust a
vehicle or pedestrian, the colour distribution in VISSIM can be used. For pedestrians, 4 colours can be
defined for the hair, shirt, trousers and shoes. The actual vehicle or pedestrian colours are exported to
the ANI.TXT file by VISSIM and the VISSIM 3DS script can assign them to the model parts in 3DS MAX.

1.2 Network Details

To have a smooth animation in 3DS MAX it is important to add enough detail to the VISSIM network.

1.2.1 Links Intermediate Points

A curved link should have enough intermediate points for a smooth vehicle movement. The suitable
number of points is so that the vehicle doesn’t move on a segment for two simulation steps. In the
example below; the vehicle moves straight for a few time steps then turns and then moves straight
again. In the corrected version the vehicle turns in each time step.

Too few points Correct

As the number of intermediate points does not have any strong influence on the simulation speed, it is
recommended to add as many points as necessary. To add intermediate points to an existing link without
changing the current positions the ALT key + left mouse drag can be used. (Refer to “Edit Curvature” in
the “Link Editing” section in VISSIM User Manual).

1.2.2 Links Elevation

If different network parts have different elevations it is better to define the links with the correct
elevation. But if the network has already been built without any elevation the “Drop on Road”
functionality can be used to adjust the vehicle elevation and rotations regarding the underneath surface.
To use this functionality the vehicles should be created (enter to the scene) where only one surface
exists. For more information refer to 3.2.2-Vehicles’ Elevation section in this manual.

1.3 Simulation Parameters

The number of frames per second in the created animation in 3DS MAX is a multiple of the simulation
resolution in VISSIM. For example for a 24 FPS animation 3DS MAX the best simulation resolution is 6
and for 30 FPS the best simulation resolution is 10.

1.4 Animation Start and Length

Working with a large animation in 3DS MAX is time consuming. Therefore it is recommended to watch
the simulation in VISSIM and export only the parts that you really need in your final animation to 3DS
MAX. It is possible to export many small ANI.TXT files and import them to one animation in 3DS MAX.
2. Creating 3D models for VISSIM 3DS script
The script needs to set some properties for vehicle models and to move the body parts for the
pedestrian models. Therefore the model parts should be marked such that the script can find them.
In 3DS MAX it is possible to define an object called Dummy. A dummy does not have any geometry and is
shown in view ports as a green box. This object is not shown in rendered animations. Because some third
party render engines cannot handle groups, the dummy objects are used to keep all vehicle or
pedestrian parts together.
Generally for all 3D models (vehicle and pedestrian) these properties have to be set.

1. The MAX file named the same as the 3D model in VISSIM.

2. Each MAX file contains only one 3D model.
3. In each MAX file there is only one dummy object (or a group for vehicles) that is named same as
the MAX file.
4. All model parts are the children of the dummy object.
5. The Dummy object is posed in such a way that the model size does not change.
6. All model parts which receive colour from VISSIM are attached together as one mesh.
7. The vehicle body or the pedestrian body object’s name has a “_Body” suffix.
8. The body object’s material is a Multi/Sub-Object material.
9. The material IDs are the same in all models.
10. The main object’s pivot (dummy object) is underneath the front of the model on the ground.

2.1 Preparing vehicle models

Any 3D model can be used as a vehicle model. For the vehicle, because of backward compatibility, all
model parts can be grouped together as one object that is named as the 3D model. But if you create a
new model it’s recommended to create a Dummy object and link all other objects to it.

2.1.1 Dummy and Pivot

The Dummy object is posed in such a way that the model size doesn’t change. The scrip uses the
bounding box of all entities in the model including the dummy to calculate the vehicle length or the
pedestrian height. Therefore if any part of the dummy is out off the actual model the bounding box
become larger than the model. The dummy’s pivot vector is underneath the front of the model on the
ground.

Dummy and its pivot position

2.1.2 Wheels object
Wheels are same as other vehicle objects a child of the main dummy (linked to the main dummy). Each
wheel is one object or a set of linked objects. The wheel object is named with a specific suffix. This suffix
is the same for all vehicle 3D models. The default suffixes are:
“_RF Wheel” for the right front wheel
“_LF Wheel” for the left front wheel
“_RR Wheel” for the right rear wheel
“_LR Wheel” for the left rear wheel
These values can be adjusted on the VISSIM 3DS script panel.
The wheel’s pivot is set to its centre.

Wheel’s pivot position

2.1.3 Vehicle’s body

If an object in the model named with a “_Body” suffix and has a Multi/Sub-Object material, the script
uses the exported colour from VISSIM to change the colour of one of its sub-materials. The body’s
material ID can be set on the VISSIM 3DS script panel. This ID has to be the same for all models.

2.1.4 Model Size

As mentioned before, the model length is important for a correct animation. Therefore the script
rescales the models using the exported model length from VISSIM. It is recommended to set the length
correctly so that the script does not need to rescale the models.

2.2 Preparing pedestrian models

Preparing pedestrian 3D models is a complicated process and to get a good result, it needs professional
charactering skills in 3DS MAX.
Each pedestrian model is created from two main parts; skeleton and skin. The skeleton consists of the
bones that are moved by the script, and the skin consists of the body or clothes, which are attached to
the skeleton by using the skin functionality in 3DS MAX. To create the skeleton, a script is prepared that
works the same as the internal Biped functionality in 3DS MAX but is customized for our purpose. You
can build a skin by yourself or use ready-made 3D human models.
2.2.1 Using a human 3D model as skin
Almost any human 3D model can be used as skin for skeleton. Like vehicles all model parts are attached
together as one object that is named with a “_Body” suffix. If this object’s material is a Multi/Sub-Object
material the script is able to change its colours using the exported colours from VISSIM.
To use other colour schemes than VISSIM or other materials like textures for cloths, different 3D models
should be used in VISSIM for different materials. For example the VISSIM 3D model Woman20fram4col-
02.v3d is copied to WomanRedDress.v3d and WomanBlueDress.v3d to represent women models using
textures (instead simple diffuse colour) for different cloths colour. For 3DS MAX, two different 3D models
are created for WomanRedDress and WomanBlueDress. If there is only one type of model in the
animation which has predefined colours, the “Adjust Body Materials to VISSIM” option can be turned off.
If the animation has a mixture of models which use VISSIM colours and those which have predefined
materials, the models which use VISSIM colours should use the material IDs as normal. To prevent the
script changing the colours of the other models these can either use different material IDs or have a
material type other than Multi/Sub-Object for the body object.

2.2.1 Creating and Modifying the Skeleton

To create a skeleton for a skin, start the skeleton creator script (SkeletonCreator.ms) and then load a 3D
model to be used as skin. To start creating a skeleton click the Create button on the Skeleton Creator
panel and press the left mouse button in perspective view port and drag to create a skeleton. The 3D
model may be moved or rotated to fit the skeleton.
After creating the skeleton it is possible to change its height or scale each bone if needed. To translate
the whole skeleton, choose “Move” from the script panel and also choose the move tool from the 3DS
MAX toolbar and select the skeleton’s pelvis. Before rotating the bones to fit them to the skin, the move,
scale and height modes have to be turned off. Then use the 3DS MAX rotation tool to rotate the bones to
fit them to the skin.

2.2.2 Attaching Skin and Skeleton (Skinning)

After adjusting all bones to the skin, add a skin modifier to the 3D
model and add all bones to this modifier. Refer to the 3DS MAX
skinning tutorials for more information.

2.2.3 Finalizing
To use a skinned skeleton with the script, as with the vehicle models,
all parts are linked together and the parent object is a dummy object
with the same name as the 3D model.
To finalize the model select the skeleton’s pelvis, enter the model
name in the name field on the skeleton creator panel, and then click
the Finalize button. The script links all objects together and hides the
skeleton and the dummy. This model has to be saved with the same
name as the 3D model in VISSIM.
3. VISSIM 3DS MAX panel
The VISSIM 3DS script panel contains two parts, one to import
VISSIM objects and the animation and one to set the importing
options.

3.1 Import
This rollout contains 2 buttons to import VISSIM links/areas and to
import VISSIM animation.
The info panel shows the information during the import of the
animation. On this panel:
Actual FPS is the real frames per second of the imported
animation. The exported animation from VISSIM can created from 1 to 10 frames per simulation
seconds. It is called in VSSIM simulation resolution. This value is shown on the panel after starting the
import. The number of frames per seconds that best fit the desired FPS (that can be set in Option panel)
is calculated using the simulation resolution. This value is shown for the Actual FPS. The actual FPS is a
multiple of the simulation resolution. For example for a 24 FPS animation the maximum simulation
resolution is 6 and for a 30 FPS, the maximum simulation resolution is 10.
The Frame # shows the current imported frame during importing.

3.1.1 Importing Links and Areas

All links and areas from a VISSIM network can be imported to 3DS MAX. These objects are imported as
an editable mesh and attached together as an object. The script set its name to “Road Surface” by
default. This default name can be changed in the default options at the top of the script code.
This mesh shows where the vehicles and pedestrians move, therefore it can be used as a guide line to
create or adjust the road surfaces.

3.1.2 Importing Animation

This button is used to import the exported ANI.TXT file from VISSIM. After clicking this button an open
file dialog is shown to select an ANI.TXT file to import. During the import the FPS, simulation resolution
and frame # is shown on the info panel. If any of the needed 3D models are missing, a dialog is shown so
that a 3D model can be selected. If this dialog is cancelled when searching for a vehicle model a box is
used in its place. If it is cancelled when searching for a pedestrian model, the script tries to load a model
called “DefaultSkeleton.max”. If the “DefaultSkeleton.max” cannot be found then a cylinder is used in its
place.
3.2 Options
Some script functions can be activated, deactivated or adjusted on the Options panel. The import speed
can be improved by turning not needed options off. If an option is always needed to be changed, the
option’s default values can be changed in the script code.

3.2.1 Animation
Frame Per Second can be set for the result animation. The result
FPS is a multiple of the simulation resolution that is close to this
value.
Start Frame defines the start time of the imported animation.
With this option many ANI.TXT files can be imported into one
animation.

3.2.2 Vehicles’ Elevation

If the Drop vehicle on road is checked the vehicle is moved (in Z
direction) and rotated around the Z and its X (driving) axes to fit
on the nearest face of the selected object as Road Surface. This
function works well if there is only one face of the Road Surface at
the vehicle’s starting point (where the vehicle is shown in the
animation for the first time). After the first movement, always the
nearest face to the last position (in Z direction) is chosen, so the
vehicle stays on its way and doesn’t jump on the other road
surface when it is under a bridge.
Using this functionality makes it possible to use road surfaces with
cross slope which does not exist in VISSIM.
If he script can’t find any face under the vehicle or if the option is
turned off, the exported elevation from VISSIM is used.
The road surface object must be one of the suitable objects for the
"intersectRay" function in 3DS MAX script. This function works if
the world state of the node (the state of the node at the top of the
node's stack) has a surface, such as an editable mesh, a Standard,
Extended, or Compound Primitive, or a Patch or NURBS surface
object. Splines and NURBS curves do not have a surface.
To select a road suface the Select Road Surface button can be used
to select an object in a view port. The script shows the selected
object name in the Road Surface field.
The script can only handele one object as the road surface.
Therefore all objects have to be attached together if there are
more than one.
3.2.3 Body Material
If there is an object in the vehicle/Pedestrian model that is named with “_Body” suffix, the script sets the
exported VISSIM colours to it. This object’s material has to be Multi/Sub-Object material and the Sub-
materials IDs for the parts that receive the VISSIM colour have to be set on the script panel.
VISSIM exports 4 colours for the pedestrians in this order:
Colour 1: Shirt
Colour 2: Hair
Colour 3: Trousers
Colour 4: Shoes
The IDs can be set to zero to be ignored by the animation.
The vehicles use only the Colour ID 1 for the vehicle’s body. The Colour ID 1 has to be the same for the
vehicles and pedestrians.

3.2.4 Wheels
The script can rotate the vehicle wheels and also turn the front wheels to simulate the steering wheel. To
use this feature, the wheels have to be named with specified suffix to be found by the script. These
suffices can be set here. The script searches in each vehicle for objects whose names contain these
words. Therefore it’s important to choose the names in such a way that there is no conflict.

3.2.5 Lights
If the vehicle’s body object (the object with “_Body” in the name) has a Multi/Sub-Object material and
the given sub-material ID for the light is a blend material, the script changes the blend material’s mix
amount to 100 when the light is on and to 0 when the light is off. The turning times are exported from
VISSIM.