Python API for interactions with the OpenAlea platform?

[GeraultTr]

Hi, I'm reaching out being interested in using Helios Radiation Model within our python based FSPM modeling platform, OpenAlea. In this platform we mainly use the C++ Caribu light model but it is not maintained and there is no proper python API, everything is file i/o on disk which makes it very slow, so that everybody only use it with only direct interception to save computation time.

This is why I am willing to use Helios instead and I am wondering if you might have guidelines to build an API that would effitiently exchange triangles sets, scene parameters and return PARa and energy, for the whole spectrum as a first step.

Thanks in advance for any help!

[bnbailey-psl]

Hi Tristan,

Thanks for your interest in Helios. We currently don't have a Python API for Helios. There may be plans to move ahead with this in the next year or so, but not at the moment. Here are a few ideas in the meantime:

1. The easiest but least efficient thing to do would be what you were doing with Caribu, which is to use file I/O to communicate between the two. The project builder plug-in has the ability to control the radiation model inputs and input geometry via XML files. The result could be written back to file in a number of different ways that are built-in to Helios, including XML, text files, etc. Of course the drawback is speed as you already know.

2. A compromise could be to use XML files to control the radiation model, and make a very fit-for-purpose minimal Python API to pass the geometry and triangle-level radiative inputs and output fluxes. In this case, the XML files should be very small and fast to read/write, and you could pass the more expensive data directly. Perhaps with recent AI tools this wouldn't be too difficult. Somebody in my lab developed an initial proof of concept Python API you could also use as a starting point (it is a private repo, but I could give you access). I've pasted the README below. It doesn't do the radiation plug-in though as far as I'm aware.

Those are some initial thoughts, short of implementing a full API. Then perhaps in the next year or so we might have a full comprehensive API.

PyHelios

Python bindings for Helios

For complete documentation of this software, please consult https://baileylab.ucdavis.edu/software/helios, or open the file doc/example folder for usage examples.

Warning: This library only works on Windows x64-based systems

Installation

1. Clone Repository

$ git clone https://github.com/PlantSimulationLab/PyHelios

$ cd PyHelios/

2. Install library locally

$ pip install -e .

Usage

• Creating a basic Context and adding a Patch

from pyhelios import Context
from pyhelios import DataTypes

context = Context()

center = DataTypes.Vec3(2, 3, 4)
size = DataTypes.Vec2(1, 1)
color = DataTypes.RGBcolor(0.25, 0.25, 0.25)

patch_uuid = context.add_patch(
    center=center,
    size=size,
    color=color
)

• Creating a Lemon tree and an Olive tree using WeberPennTree plugin

from pyhelios import Context, WeberPennTree, WPTType

context = Context()
wpt = WeberPennTree(context)

tree_id_lemon = wpt.build_tree(WPTType.LEMON)
tree_id_olive = wpt.build_tree(WPTType.OLIVE)

[bnbailey-psl]

On second thought, looking through what we have already for PyHelios, I think I could put together something working pretty quickly. This would be a nice thing to have in general. I will put something together and make the PyHelios repo public once I have a minimal working framework that's verified to work.

[GeraultTr]

Hi,

Thank you for your detailed answer, I will indeed be very curious about PyHelios and I am willing to help you on this task if you think we could come up with something rather quickly, just let me know. Even for a minimalistic first API, I think that it would give a good example of where to start.

[bnbailey-psl]

Tristan,

The PyHelios repo is now live: https://github.com/PlantSimulationLab/PyHelios

It has basic documentation here: https://plantsimulationlab.github.io/PyHelios

It should work on all platforms, and have basic functionality for radiation model integration. For now you need to compile the core Helios C++ library using the build script, as detailed in the documentation. In the near future I plan to have pre-built distributions so you don't have to do this part.

The key ways I anticipate it will interface through your code will be:

1. Transferring model geometry to PyHelios: There are several different ways to get geometry into PyHelios (from PLY, OBJ, or XML files), but I suspect you'll not want to do it through the filesystem, so there is a function Context::addTrianglesFromArrays() or Context::addTrianglesFromArraysTextured() that follows trimesh/Open3D for specifying mesh geometry you can use to transfer the geometry.
2. Setting input attributes (e.g., radiative properties): This is done using Context::setPrimitiveData[*](), analogous to how it is done in the C++ code. Whatever function is used to add geometry returns an array of UUID identifiers, which can be used to set properties like reflectivity.
3. Setting up the radiation simulation: This is virtually the same as the C++ code. You can reference the PyHelios or Helios documentation on how to set this up, or the YouTube tutorials.
4. Getting results back (e.g., radiative fluxes): This can be done on an element-by-element basis using Context::getPrimitiveData(), or in bulk for many elements using Context::getPrimitiveDataArray() using UUIDs.

Two good examples to look at are in docs/examples/radiation_stanford_bunny.py and docs/examples/external_geometry_sample.py.

I would recommend to familiarize yourself with the Helios C++ usage, as the documentation is more complete and using PyHelios is almost exactly the same. The YouTube tutorials also show how to build the C++ code (if you have trouble with the automated scripts) and how to do basic radiation simulations.

I will continue to add functionality. The code is likely to change quickly and may not be backward compatible until v1.0, so check docs/CHANGELOG.md when you update your version. Also let me know if something does not work or if there are documentation errors. I have fairly extensive automated testing, so my expectation is that everything that has been implemented should work.

[GeraultTr]

Thank you very much for your fast reply and this first version, we'll make sure to get back to you if we have any question, although your existing documentation is very clear and I can easily see a path to get to a working test with the steps above. Compiling Helios core works fine on my side so using the api should then be straightforward by passing triangularized plant meshes and mapping the results with an indexer.

Once we have a working example I'll send it to you if you want to include it in the examples, and we'll use it to compare results from Helios, Caribu, RATP, VPL's raytracer and GPUflux (and other light models used with FSPMs I may not be aware of). @pradal told me he will get in touch with you about this benchmark when we get there.