VISSIM® 3DS MAX® Script User Guide
VISSIM® 3DS MAX® Script User Guide
VISSIM® 3DS MAX® Script User Guide
You also want an ePaper? Increase the reach of your titles
YUMPU automatically turns print PDFs into web optimized ePapers that Google loves.
VISSIM ® <strong>3DS</strong> MAX ®<br />
<strong>Script</strong><br />
<strong>User</strong> <strong>Guide</strong><br />
Intro<br />
This script is created to import the VISSIM animation from ANI.TXT files to <strong>3DS</strong> MAX. A successful<br />
animation import depends on three items.<br />
1. Correct settings and modelling in VISSIM.<br />
2. Creating 3D models for the VISSIM <strong>3DS</strong> script.<br />
3. Correct settings in the VISSIM <strong>3DS</strong> MAX panel.<br />
This user guide describes these items.<br />
All necessary scripts, 3D models and Tutorials can be found in \API\3dsMaxExport.
1. Modelling in VISSIM<br />
To create a suitable network model for <strong>3DS</strong> MAX in VISSIM these items should be adjusted correctly.<br />
1. 3D models and colour distributions.<br />
2. Network details.<br />
3. Simulation parameters.<br />
4. Animations start time and length.<br />
1.1 3D models and colour distribution<br />
Two properties of the VISSIM 3D models are important for the animation; the 3D model’s name and<br />
dimensions.<br />
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<br />
pedestrian. Therefore for each 3D model from VISSIM’s vehicle 3D model distribution, a <strong>3DS</strong> MAX model<br />
should be created. If you want to use your own fleet, the best way is to convert them to V3D files for<br />
VISSIM. If this is not possible, an existing VISSIM 3D model (V3D file) can be renamed and used instead of<br />
the missing model. But the 2D dimensions in the VISSIM model have to be adjusted to have the same<br />
vehicle length. (For more information refer to the “3D Model Distribution” section in VISSIM <strong>User</strong><br />
Manual)<br />
The model dimensions are very important for the simulation and the imported animation. If the vehicle’s<br />
<strong>3DS</strong> MAX model is smaller or larger than the model in VISSIM, the vehicles may overlap or may be too far<br />
apart in the imported animation in <strong>3DS</strong> MAX.<br />
The vehicle colours from VISSIM can be used to colour the vehicle in <strong>3DS</strong> MAX. To define or adjust a<br />
vehicle or pedestrian, the colour distribution in VISSIM can be used. For pedestrians, 4 colours can be<br />
defined for the hair, shirt, trousers and shoes. The actual vehicle or pedestrian colours are exported to<br />
the ANI.TXT file by VISSIM and the VISSIM <strong>3DS</strong> script can assign them to the model parts in <strong>3DS</strong> MAX.<br />
1.2 Network Details<br />
To have a smooth animation in <strong>3DS</strong> MAX it is important to add enough detail to the VISSIM network.<br />
1.2.1 Links Intermediate Points<br />
A curved link should have enough intermediate points for a smooth vehicle movement. The suitable<br />
number of points is so that the vehicle doesn’t move on a segment for two simulation steps. In the<br />
example below; the vehicle moves straight for a few time steps then turns and then moves straight<br />
again. In the corrected version the vehicle turns in each time step.<br />
Too few points Correct
As the number of intermediate points does not have any strong influence on the simulation speed, it is<br />
recommended to add as many points as necessary. To add intermediate points to an existing link without<br />
changing the current positions the ALT key + left mouse drag can be used. (Refer to “Edit Curvature” in<br />
the “Link Editing” section in VISSIM <strong>User</strong> Manual).<br />
1.2.2 Links Elevation<br />
If different network parts have different elevations it is better to define the links with the correct<br />
elevation. But if the network has already been built without any elevation the “Drop on Road”<br />
functionality can be used to adjust the vehicle elevation and rotations regarding the underneath surface.<br />
To use this functionality the vehicles should be created (enter to the scene) where only one surface<br />
exists. For more information refer to 3.2.2-Vehicles’ Elevation section in this manual.<br />
1.3 Simulation Parameters<br />
The number of frames per second in the created animation in <strong>3DS</strong> MAX is a multiple of the simulation<br />
resolution in VISSIM. For example for a 24 FPS animation <strong>3DS</strong> MAX the best simulation resolution is 6<br />
and for 30 FPS the best simulation resolution is 10.<br />
1.4 Animation Start and Length<br />
Working with a large animation in <strong>3DS</strong> MAX is time consuming. Therefore it is recommended to watch<br />
the simulation in VISSIM and export only the parts that you really need in your final animation to <strong>3DS</strong><br />
MAX. It is possible to export many small ANI.TXT files and import them to one animation in <strong>3DS</strong> MAX.
2. Creating 3D models for VISSIM <strong>3DS</strong> script<br />
The script needs to set some properties for vehicle models and to move the body parts for the<br />
pedestrian models. Therefore the model parts should be marked such that the script can find them.<br />
In <strong>3DS</strong> MAX it is possible to define an object called Dummy. A dummy does not have any geometry and is<br />
shown in view ports as a green box. This object is not shown in rendered animations. Because some third<br />
party render engines cannot handle groups, the dummy objects are used to keep all vehicle or<br />
pedestrian parts together.<br />
Generally for all 3D models (vehicle and pedestrian) these properties have to be set.<br />
1. The MAX file named the same as the 3D model in VISSIM.<br />
2. Each MAX file contains only one 3D model.<br />
3. In each MAX file there is only one dummy object (or a group for vehicles) that is named same as<br />
the MAX file.<br />
4. All model parts are the children of the dummy object.<br />
5. The Dummy object is posed in such a way that the model size does not change.<br />
6. All model parts which receive colour from VISSIM are attached together as one mesh.<br />
7. The vehicle body or the pedestrian body object’s name has a “_Body” suffix.<br />
8. The body object’s material is a Multi/Sub-Object material.<br />
9. The material IDs are the same in all models.<br />
10. The main object’s pivot (dummy object) is underneath the front of the model on the ground.<br />
2.1 Preparing vehicle models<br />
Any 3D model can be used as a vehicle model. For the vehicle, because of backward compatibility, all<br />
model parts can be grouped together as one object that is named as the 3D model. But if you create a<br />
new model it’s recommended to create a Dummy object and link all other objects to it.<br />
2.1.1 Dummy and Pivot<br />
The Dummy object is posed in such a way that the model size doesn’t change. The scrip uses the<br />
bounding box of all entities in the model including the dummy to calculate the vehicle length or the<br />
pedestrian height. Therefore if any part of the dummy is out off the actual model the bounding box<br />
become larger than the model. The dummy’s pivot vector is underneath the front of the model on the<br />
ground.<br />
Dummy and its pivot position
2.1.2 Wheels object<br />
Wheels are same as other vehicle objects a child of the main dummy (linked to the main dummy). Each<br />
wheel is one object or a set of linked objects. The wheel object is named with a specific suffix. This suffix<br />
is the same for all vehicle 3D models. The default suffixes are:<br />
“_RF Wheel” for the right front wheel<br />
“_LF Wheel” for the left front wheel<br />
“_RR Wheel” for the right rear wheel<br />
“_LR Wheel” for the left rear wheel<br />
These values can be adjusted on the VISSIM <strong>3DS</strong> script panel.<br />
The wheel’s pivot is set to its centre.<br />
Wheel’s pivot position<br />
2.1.3 Vehicle’s body<br />
If an object in the model named with a “_Body” suffix and has a Multi/Sub-Object material, the script<br />
uses the exported colour from VISSIM to change the colour of one of its sub-materials. The body’s<br />
material ID can be set on the VISSIM <strong>3DS</strong> script panel. This ID has to be the same for all models.<br />
2.1.4 Model Size<br />
As mentioned before, the model length is important for a correct animation. Therefore the script<br />
rescales the models using the exported model length from VISSIM. It is recommended to set the length<br />
correctly so that the script does not need to rescale the models.<br />
2.2 Preparing pedestrian models<br />
Preparing pedestrian 3D models is a complicated process and to get a good result, it needs professional<br />
charactering skills in <strong>3DS</strong> MAX.<br />
Each pedestrian model is created from two main parts; skeleton and skin. The skeleton consists of the<br />
bones that are moved by the script, and the skin consists of the body or clothes, which are attached to<br />
the skeleton by using the skin functionality in <strong>3DS</strong> MAX. To create the skeleton, a script is prepared that<br />
works the same as the internal Biped functionality in <strong>3DS</strong> MAX but is customized for our purpose. You<br />
can build a skin by yourself or use ready-made 3D human models.
2.2.1 Using a human 3D model as skin<br />
Almost any human 3D model can be used as skin for skeleton. Like vehicles all model parts are attached<br />
together as one object that is named with a “_Body” suffix. If this object’s material is a Multi/Sub-Object<br />
material the script is able to change its colours using the exported colours from VISSIM.<br />
To use other colour schemes than VISSIM or other materials like textures for cloths, different 3D models<br />
should be used in VISSIM for different materials. For example the VISSIM 3D model Woman20fram4col-<br />
02.v3d is copied to WomanRedDress.v3d and WomanBlueDress.v3d to represent women models using<br />
textures (instead simple diffuse colour) for different cloths colour. For <strong>3DS</strong> MAX, two different 3D models<br />
are created for WomanRedDress and WomanBlueDress. If there is only one type of model in the<br />
animation which has predefined colours, the “Adjust Body Materials to VISSIM” option can be turned off.<br />
If the animation has a mixture of models which use VISSIM colours and those which have predefined<br />
materials, the models which use VISSIM colours should use the material IDs as normal. To prevent the<br />
script changing the colours of the other models these can either use different material IDs or have a<br />
material type other than Multi/Sub-Object for the body object.<br />
2.2.1 Creating and Modifying the Skeleton<br />
To create a skeleton for a skin, start the skeleton creator script (SkeletonCreator.ms) and then load a 3D<br />
model to be used as skin. To start creating a skeleton click the Create button on the Skeleton Creator<br />
panel and press the left mouse button in perspective view port and drag to create a skeleton. The 3D<br />
model may be moved or rotated to fit the skeleton.<br />
After creating the skeleton it is possible to change its height or scale each bone if needed. To translate<br />
the whole skeleton, choose “Move” from the script panel and also choose the move tool from the <strong>3DS</strong><br />
MAX toolbar and select the skeleton’s pelvis. Before rotating the bones to fit them to the skin, the move,<br />
scale and height modes have to be turned off. Then use the <strong>3DS</strong> MAX rotation tool to rotate the bones to<br />
fit them to the skin.<br />
2.2.2 Attaching Skin and Skeleton (Skinning)<br />
After adjusting all bones to the skin, add a skin modifier to the 3D<br />
model and add all bones to this modifier. Refer to the <strong>3DS</strong> MAX<br />
skinning tutorials for more information.<br />
2.2.3 Finalizing<br />
To use a skinned skeleton with the script, as with the vehicle models,<br />
all parts are linked together and the parent object is a dummy object<br />
with the same name as the 3D model.<br />
To finalize the model select the skeleton’s pelvis, enter the model<br />
name in the name field on the skeleton creator panel, and then click<br />
the Finalize button. The script links all objects together and hides the<br />
skeleton and the dummy. This model has to be saved with the same<br />
name as the 3D model in VISSIM.
3. VISSIM <strong>3DS</strong> MAX panel<br />
The VISSIM <strong>3DS</strong> script panel contains two parts, one to import<br />
VISSIM objects and the animation and one to set the importing<br />
options.<br />
3.1 Import<br />
This rollout contains 2 buttons to import VISSIM links/areas and to<br />
import VISSIM animation.<br />
The info panel shows the information during the import of the<br />
animation. On this panel:<br />
Actual FPS is the real frames per second of the imported<br />
animation. The exported animation from VISSIM can created from 1 to 10 frames per simulation<br />
seconds. It is called in VSSIM simulation resolution. This value is shown on the panel after starting the<br />
import. The number of frames per seconds that best fit the desired FPS (that can be set in Option panel)<br />
is calculated using the simulation resolution. This value is shown for the Actual FPS. The actual FPS is a<br />
multiple of the simulation resolution. For example for a 24 FPS animation the maximum simulation<br />
resolution is 6 and for a 30 FPS, the maximum simulation resolution is 10.<br />
The Frame # shows the current imported frame during importing.<br />
3.1.1 Importing Links and Areas<br />
All links and areas from a VISSIM network can be imported to <strong>3DS</strong> MAX. These objects are imported as<br />
an editable mesh and attached together as an object. The script set its name to “Road Surface” by<br />
default. This default name can be changed in the default options at the top of the script code.<br />
This mesh shows where the vehicles and pedestrians move, therefore it can be used as a guide line to<br />
create or adjust the road surfaces.<br />
3.1.2 Importing Animation<br />
This button is used to import the exported ANI.TXT file from VISSIM. After clicking this button an open<br />
file dialog is shown to select an ANI.TXT file to import. During the import the FPS, simulation resolution<br />
and frame # is shown on the info panel. If any of the needed 3D models are missing, a dialog is shown so<br />
that a 3D model can be selected. If this dialog is cancelled when searching for a vehicle model a box is<br />
used in its place. If it is cancelled when searching for a pedestrian model, the script tries to load a model<br />
called “DefaultSkeleton.max”. If the “DefaultSkeleton.max” cannot be found then a cylinder is used in its<br />
place.
3.2 Options<br />
Some script functions can be activated, deactivated or adjusted on the Options panel. The import speed<br />
can be improved by turning not needed options off. If an option is always needed to be changed, the<br />
option’s default values can be changed in the script code.<br />
3.2.1 Animation<br />
Frame Per Second can be set for the result animation. The result<br />
FPS is a multiple of the simulation resolution that is close to this<br />
value.<br />
Start Frame defines the start time of the imported animation.<br />
With this option many ANI.TXT files can be imported into one<br />
animation.<br />
3.2.2 Vehicles’ Elevation<br />
If the Drop vehicle on road is checked the vehicle is moved (in Z<br />
direction) and rotated around the Z and its X (driving) axes to fit<br />
on the nearest face of the selected object as Road Surface. This<br />
function works well if there is only one face of the Road Surface at<br />
the vehicle’s starting point (where the vehicle is shown in the<br />
animation for the first time). After the first movement, always the<br />
nearest face to the last position (in Z direction) is chosen, so the<br />
vehicle stays on its way and doesn’t jump on the other road<br />
surface when it is under a bridge.<br />
Using this functionality makes it possible to use road surfaces with<br />
cross slope which does not exist in VISSIM.<br />
If he script can’t find any face under the vehicle or if the option is<br />
turned off, the exported elevation from VISSIM is used.<br />
The road surface object must be one of the suitable objects for the<br />
"intersectRay" function in <strong>3DS</strong> MAX script. This function works if<br />
the world state of the node (the state of the node at the top of the<br />
node's stack) has a surface, such as an editable mesh, a Standard,<br />
Extended, or Compound Primitive, or a Patch or NURBS surface<br />
object. Splines and NURBS curves do not have a surface.<br />
To select a road suface the Select Road Surface button can be used<br />
to select an object in a view port. The script shows the selected<br />
object name in the Road Surface field.<br />
The script can only handele one object as the road surface.<br />
Therefore all objects have to be attached together if there are<br />
more than one.
3.2.3 Body Material<br />
If there is an object in the vehicle/Pedestrian model that is named with “_Body” suffix, the script sets the<br />
exported VISSIM colours to it. This object’s material has to be Multi/Sub-Object material and the Submaterials<br />
IDs for the parts that receive the VISSIM colour have to be set on the script panel.<br />
VISSIM exports 4 colours for the pedestrians in this order:<br />
Colour 1: Shirt<br />
Colour 2: Hair<br />
Colour 3: Trousers<br />
Colour 4: Shoes<br />
The IDs can be set to zero to be ignored by the animation.<br />
The vehicles use only the Colour ID 1 for the vehicle’s body. The Colour ID 1 has to be the same for the<br />
vehicles and pedestrians.<br />
3.2.4 Wheels<br />
The script can rotate the vehicle wheels and also turn the front wheels to simulate the steering wheel. To<br />
use this feature, the wheels have to be named with specified suffix to be found by the script. These<br />
suffices can be set here. The script searches in each vehicle for objects whose names contain these<br />
words. Therefore it’s important to choose the names in such a way that there is no conflict.<br />
3.2.5 Lights<br />
If the vehicle’s body object (the object with “_Body” in the name) has a Multi/Sub-Object material and<br />
the given sub-material ID for the light is a blend material, the script changes the blend material’s mix<br />
amount to 100 when the light is on and to 0 when the light is off. The turning times are exported from<br />
VISSIM.