SofaTools’s package documentation

The sofatools package was born from the need to launch several scenes with varying parameters. It is very basic but yet useful. It includes a reader/writer for vtk unstructured meshes, which allows to quickly retrieve data from 3D objects, manage DataArrays and write vtu file. Additionnaly, the affScene module can display the graph of a scene, giving an overview of complex scenes.

Install

Requirements

  • vtk

Using pip

pip install sofatools
# or python3 -m pip install --user sofatools

From sources

git clone git@gitlab.inria.fr:gdesrues1/sofatools.git

Launcher

class sofatools.Launcher(dic={})

Provides an easy to use way to launch SOFA scenes. Generates an output directory and a parameters file using json.

Parameters:dic (dict) – Dictonary with parameters
Default parameters
Key Value
SOFA_PATH Path of runSofa : path_to_sofa/bin/runSofa
SCENE_PATH Path of the python scene
G_MODE batch or qglviewer (default batch)
RESULT_DIR_PATH Directory for output and log, will be created if doesn’t exist
OUT_TO_FILE Write output in files or in terminal (default False)
STDOUT_PATH Path for standard output file (default RESULT_DIR_PATH/stdout.out)
STDERR_PATH Path for standard errors file (default RESULT_DIR_PATH/stderr.out)
DT Time step of the simulation (default 0.01)
GRAVITY Gravity (default “0 0 0”)
N_IT Number of time iterations (default 100)
__getitem__(key)

Accessor to a parameter

Parameters:key (str) – Key of the parameter in the dictionary
Returns:Value of the parameter
__setitem__(key, value)

Sets a item in the parameters dictionary

Parameters:
  • key (str) – Key of the parameter in the dictionary
  • value – Value of the parameter in the dictionary
checkRun()

This method is called before running the scene. It checks that all necessary parameters have been specified

Note

It will create the output directory if it doesn’t exist

run()

Runs the simulation calling runSofa

Note

The parameters file params.json is created in the output directory

setParams(dic)

Merges new parameters to the existing dictionary

Parameters:dic (dict) – Dictionary of the new parameters that will be added to the object
addSubDir(dirname)

Adds a subdirectory in the results tree

Parameters:dirname (str) – Full path of the directory
setResDir(i=0)

Automatically finds a name for the output directory based on the parameter RESULT_DIR_PATH as ‘dir_name_i’.

Parameters:i (int) – Optional: first number to start the recursion
cleanResDir()

Will erase all data contained in RESULT_DIR_PATH before running the simulation

Warning

Be carefull, this method erases everything contained in the directory !

Mesh

class sofatools.Mesh(filename)

Main class for unstructured mesh wrapping vtk vtkUnstructuredGrid

Parameters:filename (str) – Filename for the input mesh
Available parameters
Attribute Type Description
filename str Filename of the mesh
nbPoints int Number of points
positions list List of points position
nbCells int Number of cells
cells list List of cells
cellsType list List of cells type
nbVertices int Number of vertices
vertices list List of cells of type vertices
nbLines int Number of lines
lines list List of cells of type line
nbTriangles int Number of triangles
triangles list List of cells of type triangle
nbTetras int Number of tetrahedron
tetras list List of cells of type tetrahedra
nbHexas int Number of hexahedron
hexas list List of cells of type hexahedron
__repr__()

Provides an easy to read overview of the mesh

getPointData(name)

Accessor to the data array of name name

Parameters:name (str) – Name of the data array as it is in the vtk file
Returns:DataArray of the vtk data
getCellData(name)

Accessor to the data array of name name

Parameters:name (str) – Name of the data array as it is in the vtk file
Returns:DataArray of the vtk data
addPointData(array, name)

Add array as FIELD of name name to the dataset

Parameters:
  • array (ndarray) – Numpy array representing the data to add on the mesh vertices
  • name (str) – dataName of the added data
addCellData(array, name)

Add array as FIELD of name name to the dataset

Parameters:
  • array (ndarray) – Numpy array representing the data to add on the cells of the mesh
  • name (str) – dataName of the added data
removePointData(name)

Remove FIELD of name name from the dataset

Parameters:name (str) – dataName of the data to remove
removeCellData(name)

Remove FIELD of name name from the dataset

Parameters:name (str) – dataName of the data to remove
write(fname)

Write vtk unstructured grid to file fname

Parameters:fname (str) – Output filename
class sofatools.vtkUnstructuredGridMesh.Cells(data)

Class providing a list of all cells in the mesh

Parameters:data (vtkOutput) – vtk output of the vtk internal mesh reader
__getitem__(i)

Accessor to cell i

Parameters:i (int) – Number of the cell
__len__()

Lenght of the cells list, identical to the number of cells

__repr__()

Provides an easy to read overview of the cells list

class sofatools.vtkUnstructuredGridMesh.Cell(data, cellID)

Base class to represent a vtk cell.

Parameters:
  • cell (vtkCell) – Cell extracted from the mesh by the internal vtk mesh reader
  • cellID (int) – Vtk identifier of the cell
Static attributes
Attribute Type Description
nbP int Number of points corresponding to the cell type
ids str Name of cell corresponding to its type
Attributes
Attribute Type Description
type int Type of the cell
id int Id of the cell in the whole mesh
points list List of points id
__getitem__(i)

Accessor to the ith point id of the cell

Parameters:i (int) – Number of the point in the cell
Returns:Point id in the whole mesh
__len__()

Number of points of the cell, corresponding to the cell type

__repr__()

Provides an easy to read overview of the cell

class sofatools.vtkUnstructuredGridMesh.DataArray(vtkArray)

Base class to represent a vtk data array

Parameters:vtkArray (vtkDataArray) – Vtk data extracted from the mesh by the intenal vtk mesh reader
Attributes
Attribute Type Description
name str Name of the array as it is in the vtk mesh
range list(2) Range of the data
size int Number of data contained in the array
componentSize int Number of coordinates each data contains
__getitem__(i)

Accessor to the data in the data array

Parameters:i (int) – Number of the data in the array
Returns:The data contained in the array
__str__()

Provides an easy to read overview of the data

__len__()

Size of the data array

Graph

class sofatools.Graph(filename)

Displays the graph of a SOFA scene

Use in script:

print(Graph(filename))

Use in shell mode:

python affScene.py mesh_filename.vtk
Parameters:filename (str) – Filename of the scene