Getting started with pyvsim¶

The interface¶

There are two possible ways of talking to pyvsim. The first is using plain python code, as pyvsim behaves just like a module. This allows access to all the functionalities of the code, and is also very practical, as it also allows the integration with other scripts. Pyvsim can also be used in the python console.

The second way of interfacing with pyvsim is through environment and instruction files. This method will be preferred in the example here. Most functions can be accessed with this method, but with that, you lose the power of python.

Introduction¶

When creating a simulation with pyvsim, one has to keep in mind that the simulation elements must be contained in a tree. This is essential for performing the simulation, allowing each element to be aware of each other.

Below there is an example of a simulation tree. The user is free to create the tree in any possible way. The only limitation is that all the simulation elements must be contained in a single tree. This means that we have to add everything to the same environment, the depth, however, doesn’t matter.

Example simulation tree.

Creating an environment¶

Environments can be specified with the aid of a JSON file. The format is very simple and human-readable, and the creation of an environment is done simply by:

{
"name" : "myEnvironmentName.pyvsim"
}

In order to create a valid pyvsim environment, all elements must be included between these curly braces, and that is all!

Populating the environment¶

Now we have to populate the environment with simulation elements, for example, one can add a camera:

{
"name"      : "myEnvironmentName.pyvsim",
"camera1"   : {"type"        : "Camera"}
}

All elements in pyvsim are initialized with their reference point at the point \((0,0,0)\) pointing at the same direction as the \(x\) axis. There are a series of operations if one wants to change that.

{
"name"        : "myEnvironmentName.pyvsim",
"mySTLFile"   : {"type"             : "STL",
                 "filename"         : "./mystlfile.stl"}
}

Positioning components¶

Checking the documentation of the Component class, the following methods can be used for changing the camera position:

• rotate
• translate
• alignTo

Let’s translate the camera we have created. Checking the documentation page, one can see that we need a vector with \(\left ( \Delta x, \Delta y, \Delta z \right )\), and that the parameter name is “vector”. So we can simply write:

{
"name"      : "myEnvironmentName.pyvsim",
"camera1"   : {"type"        : "Camera",
               "translate"   : {"vector" : [1, 0, 0]}}
}

The name of the parameters and the behavior of the functions can be consulted in the Component documentation.

Assemblies are also components!, it means that you can move an entire assembly at once, except the root assembly:

{
"name"        : "myEnvironmentName.pyvsim",
"camera1"     : {"type"        : "Camera"},
"translate"   : {"vector" : [1, 0, 0]}
}

Is not possible.

Setting properties¶

Basically all pyvsim objects have many options that can be set, tuned and tweaked to represent a wide range of measurement equipment.

For example, the Camera class has a property “body” that can take the property “color” as a RGB vector:

{
"name"        : "myEnvironmentName.pyvsim",
"camera1"     : {"type"        : "Camera",
                 "translate"   : {"vector" : [1, 0, 0]},
                 "body.color"  : [1,1,1]}
}

Then the camera body will be red.

Executing pyvsim¶

Now that we have a simple scenario set up, we can execute pyvsim.

At the root of the pyvsim directory, you can find the script pyvrun, that is the batch mode of pyvsim. If issue the following command:

python pyvrun.py -h

The usage of the script is printed:

usage: Executes pyvsim in a command line interface [-h] [--geometry]
                                                   [--simulation] --filename
                                                   FILENAME [--plot {0,1}]

optional arguments:
  -h, --help           show this help message and exit
  --geometry           Reads a scenario file and generates a pyvsim scenario
                       file
  --simulation         Reads a pyvsim command file and execute the simulation
  --filename FILENAME  Filename
  --plot {0,1}         Toggle plotting of the scenario

So, assuming we save our file in the pyvsim root directory as myenvironment.json, we can issue the following command:

python pyvrun.py --geometry --filename ./myenvironment.json --plot 1

Will yield the following a scenario as shown in the figure below (if you can’t see anything, try pressing “R” for resetting the zoom in the display window):

The rendered scenario

The scenario will be saved to a file with the name specified in the “name” field, for our example, it will be myEnvironmentName.pyvsim.

Simulating¶

Now that we have a working scenario, a simulation case can be executed. This is done through another file.

Why using two files?

Apart from the obvious situation, when one wants to execute several different analysis using a single scenario, there is an important difference that has to be kept in mind:

Commands in the scenario file are not executed in a specified order

So, the command file we are going to create is important in the sense that we can specify how the simulation is going to be executed.

As usual in pyvsim, a command file is a JSON file. There are only two fields that are recognized:

• scenario - the pyvsim file containing the scenario
• commands - the commands to be executed

So, a command file will look like this:

{
"scenario" : "myEnvironmentName.pyvsim",
"commands" : []
}

Note that the commands will stay in square braces. This guarantees that they are going to be executed in the correct order.

One command we can issue is the “initialize” method of the camera. This is used for calculating the camera mapping (world to sensor coordinates), its field and depth of view. In order to issue a command, we just have to indicate the object name and the name of the command (that we can find in the Camera documentation):

{
"scenario" : "myEnvironmentName.pyvsim",
"commands" : [["camera1", {"initialize" : {}}]]
}

The structure of a command is important, so let’s explain it.

The first part is the name of the object, in our case, “camera1”.

The command name shall come in curly braces, as we can use that to pass parameters. As the method “initialize” takes no parameters, the parameters will be empty for now.

Then, the procedure is known. We will save the commands file as mycommands.json and issue the following command:

python pyvrun.py --simulation --filename ./mycommands.json --plot 1

Which yields the following result:

A more complicated series of commands can also be easily issued. For example, imagine we are to translate the camera before executing its initialization.

First, we have to check the translate documentation in the Component page. From that we know that the method takes a parameter named “vector”.

Then, the commands file becomes:

{
"scenario" : "myEnvironmentName.pyvsim",
"commands" : [["camera1", {"translate"  : {"vector" : [1, 0, 0]}}],
          ["camera1", {"initialize" : {}                    }]]
}

Which is completely different from:

{
"scenario" : "myEnvironmentName.pyvsim",
"commands" : [["camera1", {"initialize" : {}                    }],
          ["camera1", {"translate"  : {"vector" : [1, 0, 0]}}]]
}

When executing these files, think about the following problem: when you have a mapping from world coordinates to sensor coordinates, what happens if you move the camera?

This concludes this quick launch guide of pyvsim.