API References#

Release:: 0.2.1.dev1+gcbbd9f4.d20250505
Date:: May 05, 2025

The exact API of all functions and classes, as given by the docstrings. The API documents expected types and allowed features for all functions, and all parameters available for the algorithms.

openalea.plantconvert#

Generic interface to handle a plant object#

class openalea.plantconvert.plant.Plant(file: str = 'None', ignored_attrs=[], verbose=False)[source]#

Bases: object

General interface for plantconvert.

This class allows to read from different file types and to export other file types.

The supported types are :: .mtg .opf .vtk .gltf

Parameters:

file (str, optional) – name of the file to read using the read method. Defaults to None.
ignored_attrs (list of string, optional) – a list of attributes that will not appear in the final exported file in addition to attributes from RESERVED_NAMES. Defaults set to empty list.
verbose (bool, optional) – verbose mode, more information will be printed on the screen if you activate it. Defaults to False.

read()[source]#

Analyse file type from extension and reads it.

This method also prepare the self.mtg object so that it can be written again in any other file format.

write(filename)[source]#

Write the Plant object to file.

Parameters:: filename (string) – output file. Extension will determine which format will be used

openalea.plantconvert.plant.plant_from_mtg(g: MTG) → Plant[source]#

Generate a plant object from an mtg.MTG object.

Note: This can be usefull if we couple this package to another openalea package and want to save to another format.

Parameters:: g (mtg.MTG) – mtg object of the plant we later want to write
Returns:: Plant object that embeds the mtg.MTG objects.
Return type:: plantconvert.Plant

Internal functions for binary format#

openalea.plantconvert.binary_tools.pack_vec_array(vec_array, dtype)[source]#

Transform the input array of vectors into a binary string.

Parameters:

vec_array (array) – list of vectors
dtype (str) – data type

Returns:

binary string that store the data in compact way, and always pack bytes

in litte endian order. You can write the binary string into a file when you open it by ‘wb’. :rtype: bytes

Geometry related functions#

openalea.plantconvert.geometry.get_scene(g: MTG, filter=None)[source]#

Generate a plantGL Scene object from mtg geometry properties.

This method traverses the mtg g and reads the geometry property of the nodes that are allowed by the filter. It creates a plantgl Scene object of all geometric objects combined.

Parameters:

g (mtg.MTG) – mtg object that contains the plant
filter (function, optional) – takes 2 inputs: mtg.MTG and node ID and returns a bool. Defaults to None, i.e. all nodes are taken into account.

Returns:

plantGL Scene object containing all geometric objects

Return type:

plantGL.Scene

openalea.plantconvert.geometry.mat_from_transformed(geo)[source]#

Extract the global transformation matrix from a transformed geometry.

Parameters:: geo (plantgl.Geometry) – a geometry object from PlantGL
Raises:: TypeError – if the transformation is not recognized (i.e. not a plantGL instance)
Returns:: transformation matrix used to obtain the transformed geometry
Return type:: plantGL.Matrix4

class openalea.plantconvert.geometry.taper_along_x(ref_meshes=None)[source]#

Bases: object

Class with information to perform tapering along x axis.

To initialize this class with a list of reference meshes (represented by TriangleSet) If the given mesh is not in the list then it will be added.

Parameters:: ref_meshes (list) – list of reference meshes

openalea.plantconvert.geometry.tapering_radius_from_transformed(geo)[source]#

Extract the tapering radii from the input geometry.

Parameters:: geo (either a plantGL.TriangleSet, a plantGL.Tapered or a plantGL shape) – a geometry object from PlantGL
Returns:: top and base radii of the tapering geometry
Return type:: tuple

openalea.plantconvert.geometry.transformed_from_mat(A, geo, is_mesh=False)[source]#

Apply the transformation A (a 3 by 4 matrix) on the geometry.

Qr transformation of matrix A is done so that A = Q*r where:: Q is a unity matrix and r is upper-triangular. To use the oriented object of plantgl, Q should have positive determinant. r is in our case diagonal since A is a composition of rotations and scaling.

Parameters:

A (numpy.ndarray) – a 3 by 4 array that describes the transformation in the reference of the scene. This matrix is supposed to be TRS decomposible
geo (plantgl.Geometry) – a geometry object from PlantGL
is_mesh (bool) – if true a new mesh (TriangleSet) will be created. Otherwise we only create a geometry object (no duplication of mesh in the memory). Defaults to False.

Returns:

Transformed geometry. if is_mesh then we get a new mesh otherwise we only create a geometry object

Return type:

plantgl.Geometry

Plant material related functions#

openalea.plantconvert.material.to_gltf(material_data)[source]#: Create the material information accepted by GLTF, not implemented yet.

openalea.plantconvert.material.to_plantgl(material_data)[source]#

Create a plantgl object to represent a material from the input material_data.

Parameters:: material_data (dict) – dictionary that contains exactly : An Id 4 colors in RGBA : emission, ambient, diffuse and specular. shininess value.
Returns:: plantgl.Material object. Note that some information might be lost. For example, the alpha value in .opf is defined for each color (emission, etc. ) while in plantgl there is only a global alpha value : transparency = 1 - alpha
Return type:: plantgl.Material

Transformation-Matrix related functions#

exception openalea.plantconvert.matrix.TRSError[source]#: Bases: Exception

openalea.plantconvert.matrix.TRS_from_matrix4(A: ndarray)[source]#

Return the TRS components of a TRS matrix.

Parameters:: A (numpy.ndarray) – a 4x4 TRS matrix
Returns:: t, Q, s: the TRS components of the input matrix.
Return type:: tuple of numpy.ndarray vector of length 3, 3x3 matrix, vector of length 3

openalea.plantconvert.matrix.global_to_local_matrix(mat_c, mat_p=None)[source]#

Return the local matrix of mat_c in the reference of mat_p.

Parameters:

mat_c (numpy.ndarray) – a 4x4 matrix
mat_p (numpy.ndarray) – a 4x4 matrix

Returns:

the local matrix of mat_c in the reference of mat_p.

Return type:

numpy.ndarray

openalea.plantconvert.matrix.inv_TRS(A: ndarray)[source]#

Return the inverse of a TRS matrix.

Parameters:: A (numpy.ndarray) – a 4x4 TRS matrix
Returns:: inverted matrix of A of size 4x4
Return type:: numpy.ndarray

openalea.plantconvert.matrix.is_TRS(A: ndarray)[source]#

Test if the input matrix A is a 4D TRS matrix.

This requires to test if A’s linear part is the composition of a rotation and a scaling. If this is the case, the first three columns should be orthogonal.

Parameters:: A (numpy.ndarray) – a 4x4 matrix
Returns:: True if A is a TRS matrix, False otherwise
Return type:: bool

openalea.plantconvert.matrix.mat4_to_numpy(A)[source]#

Convert the pgl.Matrix4 object to a 2d array.

Parameters:: A (pgl.Matrix4) – a pgl.Matrix4 object.
Returns:: the corresponding 2d numpy array.
Return type:: numpy.ndarray

openalea.plantconvert.matrix.numpy_to_mat4(A)[source]#

Convert the 2d array A to pgl.Matrix4 object.

Parameters:: A (numpy.ndarray) – a 2d numpy array. Accepted shape = 3*4, 4*4, 3*3
Returns:: the corresponding Matrix4 object.
Return type:: pgl.Matrix4

openalea.plantconvert.matrix.random_matrix4()[source]#

Return a random TRS matrix.

Implemented for test only.

openalea.plantconvert.opf#

openalea.plantconvert.opf.const module#

Functions to read .opf files#

class openalea.plantconvert.opf.reader.Opf(OpfPath, verbose=False)[source]#

Bases: object

Class to read and write topological and geometrical opf format to OpenAlea (mtg and PlantGL).

The object contains as properties :

OpfInfo : opf file’s information

Meshesa list of reference meshes. Each mesh is represented by a dictionary

(use keys function to get the exact keys) and contains :: id : the id of the mesh points : a list of all nodes coordinates in 3D faces : the connectivity table of the mesh normal : the normal vectors at each node of the mesh textureCoords (optional) : the texture coordinates plantgl_obj : the PlantGL object that represents the mesh (TriangleSet)

Materialsa list of materials. Each material is represented by a dictionary and contains :

id : the id of the material emission : a color represented in RGBA format (the first 3 components are float value

bounded between 0,1 and should be converted to 0,255 (integer) if required)

ambient : the same as emission diffuse : the same as emission specular : the same as emission shininess : float bounded between 0 to 128 plantgl_obj : the PlantGL object that represents the material (Material)

Shapesa list of shapes. Each shape is represented by a dictionary and contains :

id : the id of the shape meshIndex : the id of the mesh to create this shape materialIndex : the id of the material to create this shape

Attributesa dictionary of attributes used to describe each organe of the plant. The keys of

this dictionary correspond to the name of the attribute while the associated value is a lambda function that convert the data to the correct type

Mtgan openalea object that reads the topology structure of the plant. The attributes of

the mtg are those read previously and geometry that is given by a shape.

Usage:

parser = Opf("simple_plant.opf")
parser.build()
parser.write_mtg("simple_plant.mtg")
print(parser.Mtg)

Parameters:

OpfPath (string) – path to the opf file that you want to parse
verbose (bool) – if True, more information will be printed on the sreen while parsing the file. The default value is False.

read_opf()[source]#

Once initialized, use this method to perform parsing.

Note: This method should be launched at most 1 time. :return: mtg object with opf information stored in its attributes. :rtype: openalea.mtg

exception openalea.plantconvert.opf.reader.Unknown_edge_type[source]#: Bases: Exception

openalea.plantconvert.opf.reader.all_empty(last_indices)[source]#

Test if all the stacks are empty.

Parameters:: last_indices (dict) – a dictionary of stacks
Returns:: True if all the stacks are empty.

Functions to write .opf files#

openalea.plantconvert.opf.writer.apply_scene(g, scene)[source]#

Add a scene to the mtg.

The scene should support the method : scene.todict() which will return a dictionary with vid as keys and the vertex’s geometry as value. In order to allow this behavior, when you define your scene from a mtg, for each shape of the scene, you should set id to be vid : shape.id = vid and then you combine the shapes to create your scene.

This function will also try to extract reference meshes and materials from the given scene (implementation is not complete yet !). But it works when each mtg node has exactly one geometric object associated if it has.

Parameters:

g (MTG.mtg) – an mtg object
scene (plantgl.Scene) – a plantgl object

openalea.plantconvert.opf.writer.write_opf(g, filename, features=None)[source]#

Write the opf file from a given MTG object.

Parameters:

g (MTG.mtg) – an mtg object, either read from a file or generated by a simulator
filename (str) – the file to write the .opf file.
features (dict, optional) – additional attributes to write in the “attributeBDD” section of the .opf file, at the root node level.

openalea.plantconvert.gltf#

Internal functions to handle buffer on .gltf files.#

openalea.plantconvert.gltf.buffer_tools.get_buffer(acsr: Accessor, g: GLTF2)[source]#: Get the buffer referenced by the accessor in a gltf asset.

openalea.plantconvert.gltf.buffer_tools.get_data(byte_string, acsr: Accessor, buffer_view: BufferView)[source]#

openalea.plantconvert.gltf.buffer_tools.get_key(d: dict, value)[source]#

Functions to read .gltf files.#

class openalea.plantconvert.gltf.reader.mtg_builder(filename)[source]#

Bases: object

build()[source]#

Functions to write .gltf files.#

class openalea.plantconvert.gltf.writer.gltf_builder(g: MTG, features: list = None)[source]#

Bases: object

Class used to build a gltf object from the mtg.

The gltf object is implemented in pygltflib :: A Python library for reading, writing and handling GLTF files. link : sergkr/gltflib.

basic usage :

builder = gltf_builder(g, features = [“Length”, “Width”]) # you should initiate an instnace with your mtg g and a list of features to be written in the gltf object.

builder.build() #by calling this method, the build.gltf object will be created according to the mtg g.

#Finally, use the gltf’s method to output a gltf file Here we choose :

builder.gltf.save_json(“test.gltf”) #here we choose to output a simple json file. The meshes are written in an embedded (when we construct the gltf object). You can choose also to output in a more compact file type. Please refer to the pygltflib’s documentation

Parameters:

g (mtg.MTG) – the mtg object
features (list or None) – a list of features to be written in the gltf object. Default is None.

build()[source]#

Build the gltf object with embedded mesh information.

Uses the methods implemented in pygltflib to output it into a file of a given type.

openalea.plantconvert.vtk#

Functions related to reading on .vtk format#

openalea.plantconvert.vtk.reader.complex_vec(g, vid)[source]#: Get all the complexes of node vid from fine to coarsest scale.

openalea.plantconvert.vtk.reader.header_to_dict(header)[source]#: Read the header as a dictionnary.

openalea.plantconvert.vtk.reader.load_topology(filename)[source]#

Load into a vtk object from the file.

Parameters:: filename (str) – the file to load
Returns:: a tuple (vtk object, header) such that the second element is the header dictionary and the first element is the vtk object.
Return type:: tuple

openalea.plantconvert.vtk.reader.mtg_from_huge_ugrid(filename)[source]#

Build a mtg from a huge unstructured grid.

(see function huge_unstructured_grid in write_vtk).

TODO : the labels are lost in the mtg

Parameters:: filename (str) – the file to load
Returns:: a mtg object built from the unstructured grid
Return type:: mtg.MTG

openalea.plantconvert.vtk.reader.mtg_from_polydata(filename)[source]#

Construct the mtg from a polydata file given by the filename.

The header of the file should be interpreted as a dictionary giving correspondance between label and it’s code.

TODO :: Solve the attributes reading

Parameters:: filename (str) – relative path to the targer file.
Returns:: a mtg object
Return type:: mtg.MTG

Functions related to writing on .vtk format#

openalea.plantconvert.vtk.writer.huge_unstructured_grid(g, mtg_iterator=None)[source]#

Construct a huge unstructured grid that encodes the geo/topo of the mtg.

The geometry is represented by a big unstructured grid obtained by concatenating all the grids of each mtg element.

TODO : rewrite the function with append data set class

The topology is given by the points data of the unstructured grid : for each point of the huge grid, there is given an attribute that indicates the id of the mtg node containing this point. The parent and the complex are also given under the data attribute in order to perfectly specify the topology.

openalea.plantconvert.vtk.writer.polydata(g, **kwargs)[source]#

Convert the topology of mtg into a polydata object.

See the specification of the corresponding polydata object in readme.

Features are stored in a dictionary that associates the features to be written with there type.

VERY IMPORTANT : The method g.reindex() is called, we may lose the correspondance before/after writing the polydata

openalea.plantconvert.vtk.writer.ugrid_from_plantgl(geo_pgl)[source]#

Create an ugrid vtk object equivalent to a plantgl geometry object.

Tesselation is applied.

openalea.plantconvert.vtk.writer.write(filename, data_set, label_dict=None, binary=True, XML=True)[source]#

Export the data set into the given file name.

The extension is managed automatically binary and xml control the output format.

API References#

openalea.plantconvert#

Generic interface to handle a plant object#

Internal functions for binary format#

Geometry related functions#

Plant material related functions#

Transformation-Matrix related functions#

openalea.plantconvert.opf#

openalea.plantconvert.opf.const module#

Functions to read .opf files#

Functions to write .opf files#

openalea.plantconvert.gltf#

Internal functions to handle buffer on .gltf files.#

Functions to read .gltf files.#

Functions to write .gltf files.#

openalea.plantconvert.vtk#

Functions related to reading on .vtk format#

Functions related to writing on .vtk format#

Indices and tables#

This Page