.. _Configuration page: Configuration *************** The VirtuaLearn3D (VL3D) framework uses YAML configuration files to define default values and internal parameters for its different subsystems. These files are located in the ``config/`` directory and are loaded at startup into the global dictionary ``VL3DCFG`` (see :mod:`src.main.main_config`). Framework components look up their defaults from this dictionary, so editing a configuration file changes the behavior of every pipeline that relies on those defaults. The configuration files are **not** pipeline specifications. Pipelines are defined in JSON files (see :ref:`Pipelines page`). The YAML configuration files provide the *default values* that pipeline components fall back to when a parameter is not explicitly set in the JSON specification. .. _Configuration loading: How configuration is loaded ============================== At startup, ``main_config_init`` reads each YAML file under ``config/`` and stores its parsed contents in a sub-key of the ``VL3DCFG`` dictionary: .. list-table:: :widths: 30 20 50 :header-rows: 1 * - File - Key - Purpose * - ``config/io.yml`` - ``IO`` - Input/output defaults (LAS version, memory proxy thresholds). * - ``config/eval.yml`` - ``EVAL`` - Evaluator defaults (raster grid, classification, uncertainty). * - ``config/report.yml`` - ``REPORT`` - Report defaults (receptive field report toggles). * - ``config/mining.yml`` - ``MINING`` - Data mining defaults (geometric, height, smooth features). * - ``config/model.yml`` - ``MODEL`` - Model defaults (RF, deep learning, architectures, receptive fields). * - ``config/test.yml`` - ``TEST`` - Test suite selection (which tests to run). Components access their defaults through a two-level lookup. For example, ``VL3DCFG['MODEL']['TransfOctoRFClassificationModel']`` returns the default dictionary for the TransfOctoRF model, while ``VL3DCFG['IO']['PointCloudArraysFactory']`` returns the LAS output defaults. When a JSON pipeline specification provides an explicit value for a parameter, it takes precedence over the YAML default. In addition, ``config/logging.yml`` is loaded separately by :mod:`src.main.main_logger` to configure Python's logging system and is not part of ``VL3DCFG``. .. _Configuration io: io.yml -- Input/Output ========================= Controls how point clouds are read and written, and when in-memory data is offloaded to disk. ``MemToFileProxy`` Configures the automatic memory-to-file proxy that dumps point cloud data to temporary files when system memory usage exceeds a threshold. -- ``mem_check_threshold`` Fraction of total system memory (0 to 1) that triggers the proxy. Default: ``0.34``. ``PointCloudArraysFactory`` Controls the LAS output format when writing point clouds from arrays. -- ``las_version`` LAS file version string. Default: ``"1.4"``. -- ``las_point_format`` LAS point record format ID. Default: ``6``. .. _Configuration eval: eval.yml -- Evaluators ========================= Provides default parameters for the evaluation components. ``RasterGridEvaluator`` Defaults for the raster grid evaluator that produces GeoTIFF outputs from point clouds. -- ``grid_iter_step`` Number of grid cells processed per iteration. Default: ``1024``. -- ``reverse_rows`` Whether to flip rows so the output matches geographic conventions. Default: ``true``. -- ``radius_expr`` Expression for the interpolation radius as a function of cell size :math:`l`. Default: ``"sqrt(2)*l/2"``. -- ``nthreads`` Number of parallel threads. Default: ``1``. ``RandForestEvaluator`` Defaults for Random Forest evaluation utilities. -- ``num_decision_trees`` Number of trees to plot. ``0`` disables plotting. Default: ``0``. -- ``compute_permutation_importance`` Whether to compute permutation-based feature importance. Default: ``true``. -- ``max_tree_depth`` Maximum depth for decision tree visualization. Default: ``5``. ``KFoldEvaluator`` Defaults for k-fold cross-validation. -- ``quantile_cuts`` List of quantiles to report. Default: ``[0.25, 0.5, 0.75]``. ``ClassificationEvaluator`` Defaults for classification evaluation, including confusion matrix formatting (colormap, font sizes, borders). ``ClassificationUncertaintyEvaluator`` Defaults for uncertainty analysis, including probability export, entropy, and optional clustering-based uncertainty decomposition. .. _Configuration report: report.yml -- Reports ========================= Controls which columns are included when exporting receptive field point clouds. ``ReceptiveFieldsReport`` -- ``include_entropies`` Include per-point entropy in exported receptive fields. Default: ``true``. -- ``include_likelihoods`` Include softmax probabilities. Default: ``true``. -- ``include_predictions`` Include predicted class labels. Default: ``true``. -- ``include_references`` Include ground-truth labels. Default: ``true``. -- ``include_success`` Include the binary success mask (prediction matches reference). Default: ``true``. -- ``include_features`` Include the NN input features. Default: ``true``. .. _Configuration mining: mining.yml -- Data Mining ============================ Default parameters for feature extraction from point clouds. Top-level keys -- ``structure_space_bits`` Precision for coordinate storage. Default: ``32``. -- ``feature_space_bits`` Precision for feature storage. Default: ``32``. ``GeomFeatsMiner`` Defaults for the Python geometric features miner. -- ``radius`` Neighborhood radius. Default: ``0.3``. -- ``fnames`` Default feature names to compute. Default: ``["linearity", "planarity", "sphericity"]``. -- ``nthreads`` Number of threads (``-1`` for all cores). Default: ``-1``. ``GeomFeatsMinerPP`` Defaults for the C++ geometric features miner. Includes neighborhood specification (type, radius, k), IDW parameters, Tikhonov regularization, and second-order estimation strategy. ``HeightFeatsMiner`` Defaults for the height features miner. Includes chunk sizes, cylindrical neighborhood parameters, and default features (``["floor_distance"]``). ``NaiveChangeMiner`` Defaults for the naive change detection miner. -- ``min_distance`` Minimum distance threshold for change detection. Default: ``0.01``. .. _Configuration model: model.yml -- Models ====================== The largest configuration file, covering machine learning models, deep learning architectures, and receptive fields. Parameters are organized by component class name. All models ----------- Top-level keys define precision for the numeric spaces: -- ``structure_space_bits`` Coordinate precision (32 or 64). Default: ``64``. -- ``feature_space_bits`` Feature precision (32 or 64). Default: ``32``. -- ``classification_space_bits`` Label precision (8, 16, or 32). Default: ``8``. Machine learning ------------------ ``RandomForestClassificationModel`` -- ``importance_report_permutation`` Use permutation importance instead of impurity-based. Default: ``true``. -- ``decision_plot_trees`` Number of trees to plot. ``0`` disables. Default: ``0``. -- ``decision_plot_max_depth`` Maximum depth for plotted trees. Default: ``5``. ``TransfOctoRFClassificationModel`` -- ``predict_batch_size`` Number of centroids per outer prediction batch (CPU gather). Default: ``8192``. -- ``predict_inner_batch_size`` Number of centroids per inner GPU batch (``predict_on_batch`` calls). Default: ``128``. -- ``predict_chunked_knn_threshold`` When the centroid count exceeds this threshold, KNN is computed per-batch via a persistent C++ octree instead of materializing the full neighbors array. Prevents OOM on large point clouds. Default: ``500000``. Deep learning -------------- Top-level deep learning keys: -- ``dl_write_keras`` Save the full Keras model (``.keras`` file) after training. Default: ``true``. -- ``dl_write_weights`` Save model weights alongside the Keras file. Default: ``true``. -- ``dl_memsafe_training`` Enable memory-safe training mode (reduces peak memory at the cost of speed). Default: ``false``. ``SimpleDLModelHandler`` Default handler parameters shared across deep learning models: -- ``run_eagerly`` Run Keras in eager mode (debugging only). Default: ``false``. -- ``training_epochs`` Default number of training epochs. Default: ``100``. -- ``batch_size`` Default training batch size. Default: ``16``. -- ``checkpoint_monitor`` Metric monitored by the checkpoint callback. Default: ``"loss"``. -- ``fit_verbose`` / ``predict_verbose`` Verbosity for ``model.fit`` and ``model.predict``. Default: ``"auto"``. -- ``skip_fit_on_zero_epochs`` Skip training entirely when ``training_epochs`` is 0. Default: ``true``. -- ``tensorboard_log_dir`` Directory for TensorBoard logs. ``null`` disables. -- ``tensorboard_histogram_frequency`` How often to log weight histograms (epochs). Default: ``0``. ``Architecture`` Default arguments for ``keras.utils.plot_model`` when exporting architecture diagrams (shapes, dtypes, layer names, DPI, etc.). The file also includes defaults for specific architectures such as ``PointNet``, ``PointNetPwiseClassif``, ``RBFNet``, ``RBFNetPwiseClassif``, ``ConvAutoencPwiseClassif``, and ``SpConv3DPwiseClassif``. Each section specifies kernel initializers, feature dimensions, skip-link strategies, batch normalization momentum, and other architecture-specific parameters. ``ReceptiveField`` -- ``structure_space_bits`` Coordinate precision for receptive fields. Default: ``32``. -- ``max_classes_per_reduction`` Maximum classes for label reduction in receptive fields. Default: ``16``. ``ReceptiveFieldHierarchicalSG`` -- ``check_discretization_rounding_error`` Validate discretization accuracy. Default: ``true``. .. _Configuration test: test.yml -- Tests ==================== Controls which test suites are executed when running ``venv/bin/python vl3d.py --test``. Tests are organized by category (data mining, clustering, input/output, deep learning, pipeline, C++). Each entry under a category names a test class. **Commented entries** (prefixed with ``#``) are disabled; **uncommented entries** are active. For example, to activate the ``TransfOctoRFTest`` and C++ binding tests while disabling all others: .. code-block:: yaml ErrorTestSuites: Deep learning: - TransfOctoRFTest C++: - VL3DPPBindingTest - VL3DPPBackendTest Test suites can also be placed under ``WarningTestSuites`` to run them without failing the overall test run on errors. .. _Configuration logging: logging.yml -- Logging ========================= Configures Python's logging system using the standard ``logging.config`` dictionary schema. This file is loaded by :mod:`src.main.main_logger`, not through ``VL3DCFG``. The default setup defines: - **Formatter** ``formatter_datetime``: timestamps with ``[YYYY-MM-DD HH:MM:SS] (LEVEL): message`` format. - **Handler** ``handler_console``: prints to stdout at DEBUG level. - **Handler** ``handler_file``: rotating file handler writing to ``virtualearn3d.log`` (8 MB per file, 32 backups). - **Logger** ``logger_vl3d``: the framework logger, attached to both handlers at DEBUG level. To change the log level for console output (e.g., show only warnings), edit the ``level`` key under ``handler_console``: .. code-block:: yaml handlers: handler_console: level: WARNING .. _Configuration summary: Summary ========= .. list-table:: :widths: 22 15 63 :header-rows: 1 * - File - VL3DCFG key - Description * - ``config/io.yml`` - ``IO`` - LAS output format, memory proxy threshold. * - ``config/eval.yml`` - ``EVAL`` - Evaluator defaults (raster, RF, k-fold, classification, uncertainty). * - ``config/report.yml`` - ``REPORT`` - Receptive field report column toggles. * - ``config/mining.yml`` - ``MINING`` - Feature miner defaults (geometric, height, change detection). * - ``config/model.yml`` - ``MODEL`` - Model, architecture, and receptive field defaults. * - ``config/test.yml`` - ``TEST`` - Active/inactive test suites. * - ``config/logging.yml`` - *(separate)* - Python logging configuration (console + rotating file).