Configuration file config.yaml

Each dataset directory can contain an optional config.yaml file that pre-configures the TomoTree application for that particular measurement. When the directory is loaded the file is parsed and its values are written directly into the application’s session state, so every subsequent slider, radio button, or toggle in the sidebar already shows the correct setting for the dataset.

This page describes the config.yaml of a dataset. The application settings in config/config.yaml (login, directories, allow_no_auth, …) are listed in the Installation Guide.


Location

The file lies in the dataset root. It describes the whole dataset (tomogram, resistograph, scans, access rights), not only the tomograph measurement:

streamlit_user/<username>/Measurement_01/
├── config.yaml          ← here
├── tomogram/
│   ├── nodes.csv
│   └── speeds.csv
├── resistograph/
│   └── p1.dpa
└── backgrounds/
    └── photo.jpg

Datasets that still have the file in tomogram/config.yaml keep working (the file is read and written there as long as the root has none). Move it with python -m tomotree.importers migrate <dataset> (make migrate-datasets). See the section Where Your Data Are Stored of the User Guide for details.

Files referenced by the configuration (e.g. background.image) are given by file name only and are looked up in their own subdirectory (backgrounds/, resistograph/, …).


Input data

Node positions

Provide either Cartesian coordinates or pairwise distances; the application uses whichever key is present.

# Cartesian coordinates of sensors as a CSV string (x, y in metres).
# Note the | marking the start of a multi-line string. One line per node, no header.
nodes: |
  0.0;0.0
  -0.1388855641449167;-0.034055837563451805
  -0.26053412907939993;-0.13405583756345177
  -0.2926037348490796;-0.2800143824027072
  -0.2527030211439491;-0.42563620981387473
  -0.1380170864257508;-0.537565143824027
  0.0;-0.591
  0.1526909370521609;-0.5812800338409475
  0.26408687276895;-0.4892791878172589
  0.2918393428044868;-0.32928680203045674
  0.2482252001711349;-0.1755
  0.15585561338053316;-0.05416666666666666

or

# Distance table as a CSV string:  from-to, distance
distances: |
2-1,28.8
3-1,58
4-1,72.8
5-1,81.7
6-1,90.3
7-1,95.2
8-1,85.1
9-1,73.2
10-1,64.4
11-1,36.9
12-1,18.5
2-7,98.9
3-7,92.5
4-7,70.6
5-7,51.2
6-7,24.4
8-7,29.8
9-7,49.1
10-7,74.6
11-7,82.1
12-7,94.3

If neither key is present the application looks for files named nodes.csv / distances.csv in the same directory as config.yaml.

Created from a tomograph file

A folder with a tomograph file — Fakopp ArborSonic 3D .f3d, PiCUS .pit or Arbotom .abt — and without config.yaml and nodes.csv gets a config.yaml generated from that file when it is opened. Besides nodes, times, length_unit: "cm" and time_unit: "µs" it contains:

device: "PiCUS"                  # PiCUS | Arbotom | Fakopp ArborSonic 3D
sensor_direction: "anticlockwise" # sensor numbering viewed from above
                                  # (PiCUS, ArborSonic: anticlockwise; Arbotom: clockwise)
boundary_nodes: |                # PiCUS only, when its outline differs from the sensors
  ...

The tap quality checks (pairs with few or scattered taps, directions that disagree) are written as comments at the top of the file.

clockwise controls the orientation when computing positions from distances:

clockwise: false   # true → clockwise node numbering

Measurements

Provide either travel speeds (m/s) or travel times in a CSV matrix (row = tapped sensor, column = receiving sensor). Empty cells on the diagonal are fine.

speeds: |
  ;1289.0;1317.0;1373.0;1372.0;1282.0;1056.0;1002.0;1086.0;1174.0;1244.0;1384.0
  1289.0;;1413.0;1319.0;1318.0;1288.0;1129.0;953.0;1005.0;1132.0;1236.0;1292.0
  1317.0;1413.0;;1279.0;1257.0;1233.0;1152.0;1005.0;953.0;1071.0;1278.0;1346.0
  1373.0;1319.0;1279.0;;1292.0;1204.0;1135.0;1047.0;1000.0;962.0;1227.0;1374.0
  1372.0;1318.0;1257.0;1292.0;;1233.0;1139.0;1080.0;1076.0;993.0;1154.0;1319.0
  1282.0;1288.0;1233.0;1204.0;1233.0;;1174.0;1135.0;1207.0;1156.0;1061.0;1114.0
  1056.0;1129.0;1152.0;1135.0;1139.0;1174.0;;1276.0;1365.0;1325.0;1185.0;987.0
  1002.0;953.0;1005.0;1047.0;1080.0;1135.0;1276.0;;1236.0;1277.0;1222.0;1087.0
  1086.0;1005.0;953.0;1000.0;1076.0;1207.0;1365.0;1236.0;;1295.0;1258.0;1147.0
  1174.0;1132.0;1071.0;962.0;993.0;1156.0;1325.0;1277.0;1295.0;;1258.0;1192.0
  1244.0;1236.0;1278.0;1227.0;1154.0;1061.0;1185.0;1222.0;1258.0;1258.0;;1204.0
  1384.0;1292.0;1346.0;1374.0;1319.0;1114.0;987.0;1087.0;1147.0;1192.0;1204.0;

or

times: |
  ;76.1;117.2;174.2;224.5;315.5;368.1;313.5;268.6;233.1;158.0;65.2
  78.9;;86.4;125.3;151.6;230.4;363.8;299.3;397.5;294.3;196.9;121.7
  117.2;62.1;;70.3;133.2;215.0;236.4;275.8;434.9;334.8;282.2;156.9
  188.6;130.3;66.3;;77.8;166.2;179.6;247.9;392.3;373.4;358.0;233.4
  242.0;185.4;136.2;74.7;;94.5;146.4;179.0;281.6;293.7;371.8;313.2
  299.8;237.4;182.3;134.9;74.6;;110.5;137.4;236.6;242.3;314.8;363.7
  317.1;302.4;241.2;173.8;143.9;104.0;;95.9;150.2;191.0;225.3;357.9
  377.3;300.0;282.6;237.5;211.8;155.4;100.3;;96.2;114.7;168.9;257.8
  255.8;321.4;358.3;372.6;281.3;239.4;155.7;92.4;;73.5;132.8;210.7
  198.6;258.3;280.7;373.6;312.9;279.7;204.5;126.3;94.3;;80.7;165.4
  124.6;175.8;235.4;381.0;377.9;329.0;244.8;201.0;138.9;83.6;;114.8
  58.2;107.9;151.4;240.4;285.6;399.7;345.9;273.4;234.8;158.6;116.8;

As with nodes, if neither key is present the application searches for speeds.csv, velocities.csv, times.csv, and finally reads the travel times from an .f3d file. A folder with only a tomograph file gets a generated config.yaml (see above).

The search for files applies only to a legacy config.yaml without sources (next section).

Data sources (sources, active)

config.yaml is the single source of truth of a dataset. Every input file (tomograph file, nodes.csv, distances.csv, speeds.csv, velocities.csv, times.csv, scan_geometry.csv) is imported explicitly: the file stays in the dataset as an archive, sources records it, and the data of the chosen source are written into config.yaml. When sources is present, only config.yaml is read; other files in the folder are ignored.

sources:
  jicin_05.f3d:
    file: jicin_05.f3d          # relative to the dataset directory
    kind: f3d                   # pit | abt | f3d | nodes_csv | distances_csv | speeds_csv
                                # | velocities_csv | times_csv | scan_geometry | manual
    sha256: 90187e0b…           # detects a changed file
    imported: '2026-10-09'
    provides: [geometry, times]
    layers: [0]                 # multi-layer files
    notes: [...]                # tap quality checks of tomograph files
  nodes-05.csv:
    file: nodes-05.csv
    kind: nodes_csv
    units: {length: m, time: s} # CSV tables do not state their units
    ...
  manual: {kind: manual}        # data edited by hand
  # a source that was the geometry before also keeps the settings numbered by its sensors:
  #   sensor_settings: {root: {disabled_rays: [[1, 3]], sensor_direction: anticlockwise}}
active:                         # source of each quantity
  geometry: nodes-05.csv        # nodes or distances (and clockwise for distances)
  times: speeds-05.csv          # times or speeds
  boundary: scan_geometry.csv   # boundary_nodes (and boundary_sensor_vertex_indices)

With several sources of one quantity (device geometry and a 3D scan, times from the .f3d file and from a CSV table), active chooses the one used. Switching it re-imports the data from the archived file, converted to length_unit / time_unit of the config. Multi-layer datasets keep active and the data in each layer. Settings numbered by sensors (disabled_rays, nodes_subset, bark_thickness_array, sensor_direction, sensor_numbering) belong to the geometry: when the geometry source changes, the values in use are stored with the previous source (sensor_settings) and those of the new source are restored. A 3D scan chosen as the geometry also becomes the boundary source: its outline (boundary_nodes, with the sensors anchored on it) is the stem boundary, as with the legacy geometry='scan'; a boundary chosen later (or in the same select_sources call) wins. Data edited by hand in the config editor become manual. In the app, the sources are chosen on the page “Data & Info & Share → Data sources” (for each file: use it for geometry, times or boundary; Apply uses all choices at once and recomputes everything); the sidebar “Data Info & Sources” only shows them.

From Python:

from tomotree import importers
importers.import_source("Jičín_05", "Jičín_05/scan_geometry.csv")   # register; activates only missing quantities
importers.set_active("Jičín_05", "geometry", "scan_geometry.csv")   # use the scan geometry (and its outline)
importers.select_sources("Jičín_05", {"geometry": "nodes-05.csv", "times": "speeds-05.csv"})  # several at once
importers.use_source("Jičín_05", "jicin_05.f3d")                    # all data of one file
importers.check_sources("Jičín_05")    # changed / missing / new / edited files, sources that disagree by more than 2 %

A scan geometry needs travel times (not only speeds) as the active source of times. A legacy dataset without sources is converted by make migrate-datasets DATASETS="dir1 dir2" (or python -m tomotree.importers migrate dir1 dir2); the data used do not change, data already in config.yaml are attributed to the file with the same values, otherwise to manual. make check-datasets reports problems.


Units

length_unit: m      # m | cm | mm  (default: m)
time_unit: s        # s | ms | µs   (default: s)

Legacy alternative (deprecated, prefer the keys above):

conversion factors:
  length: 0.01      # multiplier to convert to metres
  time: 1.0e-6      # multiplier to convert to seconds

Access control

Each user can only see his/her own datasets and the datasets preloaded by the admin for all users.

The admin can restrict the access to these preloaded datasets using the allowed key, which takes a list of usernames as its value. For example:

allowed: [alice, bob, guest]

If the key is absent, all users have access.


Grid resolution

nx: 70   # horizontal cell count (default: 41, range 4–140)
ny: 70   # vertical cell count   (default: 41, range 4–140)

Velocity colour scale

Scale type

speed_scale: percentage of reference value   # percentile | percentage of reference value | numerical value

Bounds — numerical (m/s)

speed_min: 600.0
speed_max: 1800.0

Bounds — percentage of reference value

speed_percent_min: 50
speed_percent_max: 100

# Which value is 100 %:
reference_value: sound wood velocity   # sound wood velocity | maximal velocity | upper decile

Bounds — percentile

speed_percentile_min: 10
speed_percentile_max: 90

Tomogram appearance

plot_function: velocity      # velocity | velocity square | Edyn modulus
tomogram_type: cells only    # rays only | cells only | both |
                             # interactive, rays only | interactive, cells only
ray_width: 2.0               # ray line width in the tomogram and in the 3D scan
colormap: TomoTree           # TomoTree | viridis | plasma
shading: flat                # flat | gouraud | nearest
contourf: false              # use matplotlib contourf instead of pcolormesh
draw_boundary: false         # draw a curve along the sensor polygon
boundary_is_spline: true     # spline (true) or polygon (false) boundary
discrete_colorbar: false     # quantise the colorbar
n_discrete_colors: 5         # number of colours when discrete_colorbar is true
grid: true                   # draw grid lines on the tomogram
coordinates_alignment: origin bottom left
  # origin bottom left | origin in the sensors center |
  # origin in the pith | none
image_comparison_photo_tomogram: true
  # enable slider-based photo/tomogram comparison

Reconstruction parameters

anisotropy: true        # correct for acoustic anisotropy (Du 2015 formula)
rescale: true           # rescale cell speeds to match measured TOF (EBSI, ERSM)
fbp_correction: false   # EBSI, ERSM: correct the tomogram by back projection
fbp_correction_damping: 1.0  # damping of the back projection correction
bark_thickness: 0.0     # bark thickness in cm — sensors are shifted inward
reaction_time: 0.0      # reaction time of the device in µs, subtracted from all times (all methods)
power: 1.0              # EBSI: exponent for weighted mean (range 1–5)
max_segments: 10        # ERSM: maximum ray segments (range 1–50)
e_segmentation: 0.98    # ERSM: ellipse eccentricity for segmentation
e_interpolation: 0.99   # ERSM: ellipse eccentricity for interpolation
sirt_smoothing: 10.0    # SIRT: weight of the smoothing (0 = classical SIRT)
sirt_ray_width: 12.0    # SIRT: fat ray width in % of the tree diameter (0 = thin rays)
sirt_iterations: 2000   # SIRT: number of iterations
sirt_relaxation: 1.5    # SIRT: relaxation parameter (0.1–1.9)
sirt_speed_min: 0.0     # SIRT: minimal cell velocity in m/s (0 = automatic)
sirt_speed_max: 0.0     # SIRT: maximal cell velocity in m/s (0 = automatic)
fbp_filtered: true      # FBP: filtered (true) or plain (false) back projection
fbp_damping: 1.0        # FBP: damping of the filter
fbp_ray_width: 12.0     # FBP: fat ray width in % of the tree diameter (0 = thin rays)
rays_ray_width: 0.0     # Rays: fat ray width in % of the tree diameter (0 = thin rays)

Subset of nodes

# Use only a subset of node numbers (1-based) for reconstruction.
nodes_subset: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]

Disabled rays

# Rays left out of the reconstruction (both directions of each pair),
# as pairs of node numbers (1-based). Set in the "Select rays" dialog.
disabled_rays: [[2, 4], [3, 7]]
ray_direction_tolerance_pct: 20.0   # "Rays measured differently in the two
                                    # directions": allowed difference in %

Sound-wood speed

# Node pairs used to estimate the sound-wood reference speed.
rays_sound_wood_speed: ['1-11', '2-12', '1-3', '2-4', '3-5', '4-6', '5-7', '6-8', '7-9', '8-10', '9-11', '10-12']
speed_method_avg: Mean    # Mean | Median

Background photo

Registers a photo from the backgrounds/ subdirectory (or from photos/ when backgrounds/ does not exist, or from the dataset root when neither exists) and maps two known sensor positions to pixel coordinates so the photo can be correctly overlaid on the tomogram.

background:
  image: photo.jpeg          # filename
  from_node_value: 1         # node number for the first reference point
  to_node_value: 7           # node number for the second reference point
  coordinates:
    x1: 427.58               # pixel x of node from_node_value
    y1: 42.82                # pixel y of node from_node_value
    x2: 506.50               # pixel x of node to_node_value
    y2: 736.33               # pixel y of node to_node_value

3D scan

# Sensor numbering viewed from above, used to place the tomogram on the 3D scan.
# Overrides sensor_direction of the device.
sensor_numbering: anticlockwise   # anticlockwise | clockwise

Resistograph settings

All R_* keys control the visual parameters of the resistograph display.

R_min: 88.0              # minimum value on the resistograph scale
R_max: 180.0             # maximum value on the resistograph scale
R_depth: 25.0            # maximum drilling depth shown (cm)
R_scale_length: 25.0     # length of the reference scale bar (cm)
R_color_column_step: 300 # colour column step
R_vertical_shift: 100.0  # vertical shift of the plot
R_vertical_scale: 20.0   # zoom-out factor in the vertical direction
R_window_length: 201     # window length for the smoothing filter (odd integer)
R_polyorder: 3           # polynomial order for the Savitzky-Golay filter
R_drillbar: ['00001394', '00001400', '00001395']
  # identifiers of the drill bars to display
R_graphs: []
  # identifiers of resistograph curves to overlay
drill_path_data:          # drilling paths (Define drilling paths → Save)
  '00001394': {start: [0.12, 0.03], end: [0.25, 0.27]}   # coordinates in m

Dividing line

Settings of the page Postprocessing → Dividing line (saved by its 💾 Save to file):

split_method: ERSM       # Rays | EBSI | ERSM | SIRT | FBP
split_end_a: '5'         # first end of the dividing line (sensor number, from 1)
split_end_b: '12'        # second end of the dividing line
split_min_skipped: 3     # search: sensors in use skipped on each side of the line

Publication metadata (metadata)

Metadata of the tree for the publication on Zenodo: title, authors, licence, species, date, location, device and sizes, with Darwin Core term names (dwc:scientificName, dwc:eventDate, dwc:decimalLatitude, …). They are written by the page Zenodo and described in Publishing on Zenodo. The entry metadata.zenodo records the last upload and is never published.



Minimal example

nodes: '0.0,0.0
  -0.139,-0.034
  -0.261,-0.134
  '
speeds: ',1250.0,1300.0
  1250.0,,1350.0
  1300.0,1350.0,
  '
length_unit: m
nx: 50
ny: 50