TomoTree package description

TomoTree is a Python library and interactive web application for image reconstruction from acoustic tomography of trees. Sensors (typically 12 or 24) are attached around the circumference of a tree trunk and short acoustic pulses are sent between every pair of sensors. The measured travel times — or the derived sound speeds — are then used to reconstruct a 2D velocity map of the cross-section. Areas with reduced sound speed indicate internal defects such as rot, cavities, or mechanically weakened wood.

The package provides:

  • Several reconstruction algorithms — EBSI (Ellipse-Based Spatial Interpolation) and ERSM (Extended Ray Segmentation Method). Experimental SIRT (Simultaneous Iterative Reconstruction Technique).

  • Anisotropy correction — compensates for the well-known effect that radial rays travel at different speed than tangential rays in living tree.

  • Interactive Streamlit web GUI — load data, tune parameters, and explore results without writing any code.

  • Cloud deployment possible — you can run the web app on a server and access it from any device with a web browser.

  • Jupyter friendly — you can use the reconstruction algorithms and postprocessing tools in your own Python code or Jupyter notebooks.

  • Rich geometry model — Node, Ray, Segment, Cell, and Grid objects with full cross-references.

  • Postprocessing tools — binary thresholding, area measurement, wall-thickness estimation, moment of inertia, sound-wood speed calibration, and a dividing line separating cracks from cavities.

  • Resistograph integration — overlay drilling-resistance curves on the tomogram.

  • Export — tomogram images (configurable DPI), CSV data tables, and statistics.

  • Session save / load — persist the full application state between browser sessions.

  • Internationalization — support for multiple languages with easy translation workflow.

  • Extensive documentation — API reference, user guide, and worked examples.

  • Open source — code available on GitHub.

Note

The case studies based on TomoTree utilization are described in detail in a forthcoming paper (currently submitted for peer review). The full source code is publicly available at https://github.com/robert-marik/tomotree.

For the image reconstruction we use the EBSI method published by Du et al. (2015) and the extended ray segmentation method (ERSM), which is an extension of the method published by Du et al. (2018). See also the pseudocode in the section “EBSI and ERSM reconstruction methods” of the user guide.

Our extension of the original ray segmentation method proposed by Du et al. (2018) focuses on the segmentation step, which is a critical component of the reconstruction process. Unlike the original approach, the TomoTree implementation employs ray segments of approximately uniform length, which is more appropriate for image reconstruction because the corresponding elliptical neighbourhoods are of comparable size. Segment length is therefore not determined by a geometric progression, as in Du et al. (2018), but is set close to a reference segment length, typically derived from the distance between the two closest sensors. Because trees often exhibit irregular cross-sectional geometry, sensor spacing may vary substantially and placing two sensors close together could otherwise negatively affect the segmentation of all rays. To address this issue, TomoTree allows the user to define an upper limit on the number of segments per ray. An additional modification allows for the fact that the measured ToFs of the rays do not necessarily correspond to the times estimated from the reconstructed tomogram. During reconstruction, measured ray ToFs are first used to determine segment velocities, which are then projected into grid-cell velocities. As a result of this averaging and interpolation, the ToFs recalculated from the final IR may differ from the originally measured ToFs. To reduce this discrepancy, a linear transformation is applied to the reconstructed velocity field so that the difference between measured ToFs and IR-derived ToFs is minimised. It has been observed that algorithm performance degrades for highly irregular cross sections, as long ray paths may be divided into many segments, which can adversely affect convergence and the stability of the optimisation process.

With TomoTree, all data associated with the IR are fully accessible and can be used directly. The platform provides tools for further image processing, including generating binary tomograms to distinguish sound wood from degraded areas, measuring lengths and areas, and adjusting colour scaling based on different criteria (absolute velocity values, percentiles or fractions of the reference velocity). Users can also define specific regions of the cross section to estimate sound wood velocity. In addition, TomoTree allows the second moment of area to be computed from binary tomograms, which is particularly valuable for finite element modelling of stems and trees. The option to exclude selected sensors from the reconstruction process further enables differentiation between linear defects, such as cracks and cavity-type defects, which are otherwise represented similarly in acoustic tomography.