Technical background: how the analyses are built
This chapter is a map of the source code. For every page of the web app it lists the procedures and modules that produce the result, so that you know where to look when an analysis has to be changed or fixed.
All paths are relative to src/tomotree/.
Architecture in three layers
Every analysis is split into the same three layers:
Core library (no Streamlit) –
classes/(theTomoobject and its geometry),analysis.py,physics/,resistograph.py,scans/,util.py,transform_image.py,dataset.py. The computation lives here and can be used from Jupyter.Page module (Streamlit) –
streamlit/tomograph/,streamlit/resistograph/,streamlit/scans/,streamlit/bg.py, … It reads widget values, calls the core library, draws the figures and tables.App shell –
streamlit_app/app.py(login, data directory, menu) andstreamlit_app/page_handlers.py, which maps menu labels to page modules.
Rule of thumb: a wrong number is fixed in layer 1, a wrong widget, label or layout in layer 2, a missing or misrouted menu item in layer 3.
Request flow
streamlit_app/app.py: app()
├─ get_target_directory() choose the dataset directory
├─ streamlit_app/read_config.py: process_config_file()
│ └─ dataset.py: read_config(), select_layer(), parse_config()
│ → config (dict), data (dict of DataFrames: nodes, times, speeds, ...)
├─ streamlit_app/scan_geometry.py: select_geometry()
│ └─ scan_geometry.py: use_scan_geometry() optional geometry from a 3D scan
├─ build_menu_selection() menu defined in streamlit/menu.py
└─ page_handlers.PAGES[selected](...) dispatch to the page module
(unknown label → streamlit/premium.py: render_premium_page())
Adding or changing a page
Menu label and help text:
streamlit/menu.py(menu_data,help).Label → handler:
streamlit_app/page_handlers.py(PAGES). Each handler imports the page module lazily and passes itdata,target_dir,widgets,cfg, …Shared widgets (sliders, radio buttons, toggles) are defined in
streamlit/widgets/__init__.pyand created inapp()(setup_sliders,setup_radio_buttons,setup_toggle).The “Reproduce in Jupyter” block at the end of each page is produced by
streamlit/snippet.py(show_snippet,dataset_lines,tomo_lines,call). When you change the call of a core function on a page, change the snippet lines next to it as well, otherwise the Jupyter code no longer reproduces the page.
Data loading
Task |
Where |
|---|---|
Directory layout ( |
|
|
|
Check that a dataset has the inputs a page needs (sensor positions, times/speeds, resistograph, scans, …) |
|
YAML reading/writing preserving formatting |
|
Import of tomograph files (Fakopp |
|
Tomograph file → |
|
Sensor geometry taken from a 3D scan |
|
The core: Tomo object
classes/tomo.py: Tomo is assembled from mixins:
File |
Mixin |
Content |
|---|---|---|
|
|
constructor: nodes, rays, grid, boundary (spline/polygon/scan outline), bark, |
|
|
|
|
|
cells inside the domain ( |
|
|
|
|
|
|
Geometry objects: classes/node.py (Node), classes/ray.py (Ray,
Segment), classes/cell.py (Cell), classes/grid.py (Grid, including
set_cell_status_from_threshold and the grid plot). Numerical helpers:
classes/math.py (ellipse tests, EBSI weights, colours, centroid),
classes/lib.py (point-in-polygon, numba), classes/__init__.py (angles,
cell boundary points). The colour map is set globally in colorbar.py.
The algorithms themselves are described in EBSI and ERSM Reconstruction Algorithms.
Tomograph
Rays method, EBSI method, ERSM method
Handler:
page_handlers._page_tomogramPage:
streamlit/tomograph/tomogram.py: show_tomogram()Procedure:
widget values → reconstruction parameters (grid
nx,ny, anisotropy, EBSI power, ERSM segmentation, excluded sensors, alignment, bark); bark per node inset_bark_thickness_per_node();do_tomo()→ cachedanalysis.reconstruct(), which buildstt.Tomo(...), callsfix_velocity_EBSI()and thendo_EBSI_method()ordo_ERSM_method()(Rays:do_Rays_method(), the ray means, thin or fat rays); optional rescalingTomo.optimize_back_tomogram(); the parameters are stored int.info['params']and shown as badges above the tomogram (streamlit/tomograph/badges.py);sound wood speed:
speed_calibration.find_sound_speed_estimate()→analysis.sound_wood_speed()→Tomo.estimate_sound_wood_speed();colour scale:
analysis.color_limits(),analysis.reference_speed(), plotted quantity (velocity, velocity², Edyn):analysis.plot_function();drawing:
Tomo.plot()/plot_plotly()/plot_bokeh(), background photostreamlit/bg.py: add_background(), legendstreamlit/legends.py;statistics and ray check:
tomogram_statistics()→Tomo.cells_velocity_statistics(),Tomo.ray_time_comparison().
Ray selection: dialog
select_rays()with the clickable Bokeh plotstreamlit/tomograph/ray_selector.py; automatic suggestions fromray_geometry.py(stem_outline,rays_outside_outline,rays_direction_mismatch,sensors_in_pairs). The listst.session_state['disabled_rays'](pairs numbered from 1) goes toanalysis.reconstruct(disabled_rays=...), which sets both directions of each pair to NaN.Core modules:
analysis.py,classes/*,geometry.py(pith for alignment),util.py: show_grid.SIRT method:analysis.reconstruct(method='SIRT', sirt_...)callsdo_SIRT_method()and stores its report int.sirt_report. The page reads the parameters from thesirt_*sliders (tomogram.sirt_params(); the ray width is in % of the diameter in the GUI and a fraction inreconstruct, speed bounds 0 mean automatic). The SIRT keys entertomo_params(and the snippet) only on the SIRT page. Post-processingrescaleis not offered for SIRT.FBP method(back projection):analysis.reconstruct(method='FBP', fbp_...)callsdo_FBP_method()and stores its report int.fbp_report; widgetsfbp_filtered,fbp_damping,fbp_ray_width(tomogram.fbp_params()). SIRT and FBP share_ray_cell_system()(segments, thin/fat ray matrix) and_set_cell_slowness(). Principles:docs/backprojection.md.Post-processing of EBSI/ERSM (sidebar “Post-processing settings”):
rescale(optimize_back_tomogram, linear map of all cells; times = integral of the slowness) andfbp_correction/fbp_correction_damping(correct_with_FBP: the EBSI/ERSM result is the initial model of one FBP step; rays and segments are kept). Report int.fbp_correction_report; the keys entertomo_paramsonly when the correction is on.
Speed calibration
Handler:
_page_speed_calibrationPage:
streamlit/tomograph/speed_calibration.py: speed_calibration_app()Procedure: choice of tangential rays (
Tomo.tangential_rays, without disabled rays) and of mean or median →analysis.sound_wood_speed()→Tomo.estimate_sound_wood_speed(set_status=True)(the used cells get status 1) →Tomo.plot(status=True).The result is kept in
st.session_state['sound_wood_speed_<method>']and used by the colour scale and Binary Tomo.
Postprocessing
Binary Tomo
Handler:
_page_binary_tomoPage:
streamlit/tomograph/binary.py: binary_tomo(), threshold widgets instreamlit/tomograph/binary_threshold.pyProcedure:
threshold:
analysis.binary_threshold()(from colour scale, % of reference, percentile or value);analysis.binary_section():Grid.set_cell_status_from_threshold(), areas, centroids, moment of inertia and section modulus of sound and full section:physics.inertia_2d,physics.section_modulus,physics.polygon_area, full outlineanalysis.tree_shape()withphysics/section_properties.py: PolygonSection(tensor method) andphysics/momentum_rotation.py: compute_second_moment(fallback);wall thickness:
util.measure_walls(),util.wall_sensor_numbers(),util.find_status_change_along_line();drawing
Tomo.plot(status=True), comparison with photostreamlit/image_comparison.py,streamlit/bg.py.
Photo assessment
Handler:
_page_photo_assessmentPage:
streamlit/tomograph/photo_assessment.py: render_photo_assessment(); polygon drawing by the vendored componentstreamlit/_vendor/streamlit_polygon_editorProcedure: traced polygons + calibration line →
physics/photo_section.py:photo_sections()(scale, rotation, mirroring into metres),polygon_results()(area, I, W of full and sound part), comparison with the tomogrambinary_results(t, threshold), tablesummary(); wall thicknesses from the sensors marked on the photophoto_walls()withwall_sensor_indices().Photos and their tracings (
<photo>.tracing.json) are stored viadata_layout.data_dir(..., "photo")(photos/).
Area selection tool
Handler:
_page_areaPage:
streamlit/tomograph/area.py: measure_areas()Procedure: bounds from the text input →
analysis.area_bins()(interval of each cell, area table, usesanalysis.plot_function()) →analysis.plot_area_bins().
Tomogram measurement tool
Handler:
_page_measurePage:
streamlit/tomograph/measure.py: measure_tomogram()Procedure:
plot_tomogram()drawsTomo.plot()into an image, clicks are converted to coordinates bypixel_to_coord()/process_click()(all in the page module, no core function).
Background
Handler:
_page_backgroundPage:
streamlit/bg.py: select_image_for_background()Procedure: the user clicks sensors in the photo →
analysis.background_alignment()→transform_image.fit_similarity_transform(); the result is written into thebackground:section ofconfig.yaml(streamlit_app/read_config.py: add_to_config_file). The photo is later drawn under tomograms bybg.add_background()→transform_image.transform_image().
Dividing line
Handler:
_page_split_linePage:
streamlit/tomograph/split_line.py: split_line_page()Procedure: parameters of the method from the applied tomogram (
pending.applied(), otherwisetomo_params_from_state()) →split.split_tomogram()(whole tomogram, two halves fromsplit.split_halves()reconstructed byanalysis.reconstruct(include_only=...), merged on the grid of the whole tomogram) → sound wood speed andanalysis.color_limits()of the whole tomogram →split.split_metrics()(crossing_delayfromsplit.crossing_rays()andanalysis.ray_times(); the line is taken frommerged.info['split_line']or passed asline=). The line is drawn into both tomograms bysplit.plot_line(). Search:split.scan_split_lines()oversplit.split_lines(), drawn bysplit.plot_scan(); the result is kept inst.session_state['_split_scan'].Snippet:
split_snippet()in the page module.Settings
split_method,split_end_a,split_end_b,split_min_skippedare registry widgets and can be saved toconfig.yaml.
Angle plots
Handler:
_page_angle_plots(the page is written directly in the handler)Procedure:
streamlit/tomotree.py: plot_angular_dependence()→Tomo.plot_angular_dependence()(matplotlib or plotly), parametersangle_params(),angle_figsize().
Scan tools
The 3D scan pages share state and widgets from streamlit/scans/__init__.py
(load_scanner_model, render_scanner_settings_widgets,
compute_cross_section). The core is in scans/.
Sensor position
Handler:
_sensor_position_toolPage:
streamlit/scans/scans_sensors.py→streamlit/scans/sensor_geometry_page.py: render_sensor_geometry_page(); 3D picking instreamlit/scans/sensor_frontendProcedure (
scans/sensor_geometry.py):validate_record()→ outlinefit_boundary()(concave hull) ormesh_boundary()(mesh intersection) →validate_boundary(),orient_geometry(),move_sensors(),reverse_numbering()→ exportgeometry_archive(),scan_geometry_table(); import intoconfig.yamlwithimporters.refresh_source(). Missing surface:scans/surface_reconstruction.py: reconstruct_surface(). Red marker detection:scans/marker_detection.py: detect_markers(). Saving to the dataset:scan_geometry.csvplussensor_geometry.jsonnext to the scan (saved_geometry(),load_saved_geometry(),check_scan_plane()).The exported table is read by
scan_geometry.pyduring data loading.
Cross section
Handler:
_cross_section_toolPage:
streamlit/scans/scans_trunk.py: render_tree_trunk_scanner_page(), polygon editingstreamlit/scans/polygon_editor.pyProcedure:
scans/scantree.py:load_scan()/load_glb_file()→TreeTrunkScanner(restrict_height_range,rotate_point_cloud,find_perpendicular_slice) →cross_section(vertices, CutSettings)→CrossSectionpolygon (concave/convex hull, shapely). 3D view: three.js (streamlit_3d_viewer.show_3d_viewer), plotly or pyvista; the polygon editor component is instreamlit/scans/frontend.Tomogram or photo on the cut (three.js):
scans/tomogram_placement.py(fit_to_sensors()with a saved sensor geometry, otherwiseplace_at_sensor1(); imagetomogram_image()), photo:streamlit/tomograph/photo_on_cut.py→scans/photo_placement.py: fit_photo_to_sensors(). Jupyter version (PyVista):scans/scantree.py: tomogram_on_scan().
Cross section mechanical analysis
Handler:
_mechanical_analysis_toolPage:
streamlit/scans/scans_cross_section.py: render_tree_cross_section_scanner_page()Procedure: polygon from Cross section (session state) →
physics/section_properties.py: PolygonSection(area, perimeter, diameter,sweep()= I and W for angles −90…90°,extrema()), all computed inPolygonSectionitself (shapely, tensor or rotation method).
3D scan tools
Handler:
_scan_toolsPage:
streamlit/scans/scans_batch_browser.py: render_scan_batch_browser()Procedure: listing of
scans/directory, OBJ → GLB conversion by the external packagestreamlit_3d_viewer.converter.convert, smoothing byscans/surface_reconstruction.py: reconstruct_surface()(Poisson reconstruction in a separate process).
Resistograph
All pages create resistograph.py: Resistograph(directory=target_dir),
which reads the files from resistograph/ (read_resistograph_data) and
preprocesses them (preprocess_data, remove_global_linear_trend,
Savitzky–Golay smoothing). Checks shared by the pages are in
streamlit/resistograph/__init__.py.
Resistograph mean & std
Handler:
_page_resistograph_mean_stdPage:
streamlit/resistograph/mean_std.py: resistograph_draw()Procedure:
resistograph.plot_savgol_mean_std()orresistograph.plot_rolling_mean_std().
Resistograph
Handler:
_page_resistographPage:
streamlit/resistograph/curves.py: resistograph_curves_app()Procedure: plotly chart of
Resistograph.data, table and CSV download.
Define drilling paths
Handler:
_page_drilling_pathsPage:
streamlit/resistograph/drilling_path.py: drilling_path_setup()Procedure: manual paths or
resistograph.auto_drilling_paths(res, tomo)→set_drilling_paths()(DrillingPathobjects). The paths live inst.session_state['drill_path_data']; the Save to config file button (save_drilling_paths_to_config()) writes them asdrill_path_dataintoconfig.yaml(current layer).initialize_drilling_path_session()loads them from the config when the session has none; it is called here and on Res & Tomo.
Res & Tomo
Handler:
_page_res_tomoPage:
streamlit/resistograph/plot.py: plot_resistogram_on_tomogram()Procedure: tomogram
Tomo.plot()+set_drilling_paths()+resistograph.add_resistograph_to_image()(coloured bars along the paths) andadd_resistograph_graphs()(curves along the paths).