# 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](installation.md#1-main-configuration-file). --- ## 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//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 ` (`make migrate-datasets`). See the section *Where Your Data Are Stored* of the [User Guide](user_guide.md) 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. ```yaml # 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 ```yaml # 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: ```yaml 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: ```yaml 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. ```yaml 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 ```yaml 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. ```yaml 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: ```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 ```yaml length_unit: m # m | cm | mm (default: m) time_unit: s # s | ms | µs (default: s) ``` **Legacy alternative** (deprecated, prefer the keys above): ```yaml 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: ```yaml allowed: [alice, bob, guest] ``` If the key is absent, all users have access. --- ## Grid resolution ```yaml 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 ```yaml speed_scale: percentage of reference value # percentile | percentage of reference value | numerical value ``` ### Bounds — numerical (m/s) ```yaml speed_min: 600.0 speed_max: 1800.0 ``` ### Bounds — percentage of reference value ```yaml 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 ```yaml speed_percentile_min: 10 speed_percentile_max: 90 ``` --- ## Tomogram appearance ```yaml 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 ```yaml 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 ```yaml # 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 ```yaml # 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 ```yaml # 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. ```yaml 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 ```yaml # 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. ```yaml 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**): ```yaml 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](zenodo.md). The entry `metadata.zenodo` records the last upload and is never published. --- ## Navigation / landing page Set the tab that is shown first when the dataset is opened: ```yaml landing_page: ERSM method # any valid menu item name ``` Alternative low-level form (kept for compatibility): ```yaml config: first_level: Tomograph last_sub: Resistograph: Define drilling paths Tomograph: ERSM method ``` --- ## Minimal example ```yaml 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 ```