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.yamlof a dataset. The application settings inconfig/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