1 utils

utils

Stable cross-domain configuration, stage, console, and geometry contracts.

Specialized formatting, summaries, serialization, and domain semantics live in explicit owner leaves instead of expanding this package-root interface.

1.1 Package guide

aria_nbv.utils contains small cross-domain runtime contracts. The package root is intentionally narrow: configuration factories, Console/Verbosity, training Stage, optimization markers, and the established yaw helper remain available there. Formatting, serialization, and diagnostic details use their own explicit leaves.

1.2 Owners

console/ owns process-wide console state, tensor-aware summaries, reusable Rich formatting, and the shared Typer runner. Its package marker exposes only Console and Verbosity; consumers import summaries, formatting, and CLI execution from their named leaves.
tensor_payloads.py converts tensors, EFM wrappers, and PyTorch3D cameras to CPU msgspec payloads and reconstructs them on an explicit device.
stages.py owns stable string serialization for Stage and ValueStrEnum.
plotting/snippet.py owns complete 3D EFM snippet figures: pose and semidense selection, mesh/box traces, trajectory bounds, and Plotly frusta.
plotting/grids.py owns image grids, frame overlays, scalar-field slices, and histogram primitives. Tensor inputs are detached and moved to CPU at this presentation seam.
plotting/benchmarks.py owns paired Python/Mojo benchmark ingestion, within-stratum summaries, figures, and report persistence.
fingerprints.py, metric_reductions.py, and seeding.py remain narrow behavior owners shared by multiple scientific packages.

ASE/EFM semantic names live in aria_nbv.data_handling.ase_efm.semantics; identifier parsing lives in aria_nbv.data_handling.identifiers. Experiment tracking belongs to reporting/wandb; frame geometry and gradient logging have their own domain owners. Configuration construction, path resolution and optimization markers belong to configs; their established utility-root imports load lazily to preserve compatibility without reversing the dependency.

The snippet frustum kernel intentionally remains with snippet presentation. It uses normalized rays through an inscribed valid-radius square. Rerun frusta use image corners at camera-z depth, so merging them would erase a real rendering policy difference rather than remove duplication.

1.3 Usage

from aria_nbv.utils import Console, Stage
from aria_nbv.utils.console.summary import summarize
from aria_nbv.utils.plotting.benchmarks import load_benchmark_csv
from aria_nbv.utils.plotting.snippet import SnippetPlotBuilder
from aria_nbv.utils.tensor_payloads import to_serializable

Console.with_prefix("loader").log_summary("batch", summarize(batch))
payload = to_serializable(batch)
assert Stage.from_str("validate") is Stage.VAL

Import plotting behavior from its named leaf. The plotting package marker is navigation only and does not re-export every builder or primitive.

The console root import is supported. Former flat formatting and summary module paths are intentionally unsupported after internal consumers migrate; no forwarding modules recreate that surface.

1.4 Verification

From aria_nbv/ run:

uv run pytest tests/test_console.py tests/utils/test_rich_summary.py
uv run pytest tests/data_handling/test_utils.py tests/vin/test_backbone_evl.py
uv run pytest tests/rollouts/test_cli_typer.py
uv run pytest tests/test_plotting_helpers_refactor.py \
  tests/test_plotting_frustum_device.py tests/utils/test_plotting_utils.py \
  tests/utils/test_benchmark_plotting.py
uv run ruff check aria_nbv/utils aria_nbv/data_handling/identifiers.py

1.5 Classes

Name	Description
BaseConfig	Validate, serialize, inspect, and instantiate one configuration tree.
Console	Console wrapper that centralises formatting and convenience helpers.
Optimizable	Declarative description of an optimisable parameter.
SingletonConfig	Base class for singleton configurations.
Stage	Stages of the training lifecycle.
TargetConfig	Typed config-as-factory base whose `setup_target` returns `TargetT`.
ValueStrEnum	StrEnum variant whose string form is always its underlying value.
Verbosity	Ordered output gates shared by every `Console` instance.

1.5.1 BaseConfig

utils.BaseConfig()

Validate, serialize, inspect, and instantiate one configuration tree.

Subclasses that construct runtime objects should inherit TargetConfig and expose target_type. Plain subclasses may use setup_target as a no-op and still share TOML, cache, and CLI behavior.

1.5.1.1 Attributes

Name	Description
cache_exclude_fields	Field names to exclude from cache snapshots.
cache_exclude_extra_key	json_schema_extra key for marking fields excluded from cache snapshots.
propagation_exclude_fields	Field names that must not propagate into nested config identities.
target_type	Callable target used by `setup_target`.
target	Compatibility alias for `target_type`.
propagated_fields	Track which fields were propagated from a parent config.

1.5.1.2 Methods

Name	Description
setup_target	Instantiate or return the target object for this config, if applicable.
settings_customise_sources	Restrict default settings sources to init + optional TOML/CLI.
model_dump_jsonable	Return a JSON-serializable dump suitable for logging/checkpoint metadata.
model_dump_cache	Return a cache-friendly dump with per-field cache exclusions.
to_jsonable	Convert nested configs and common types into JSON-friendly primitives.
to_toml	Serialise the config (and nested configs) to TOML.
save_toml	Persist the configuration to a TOML file and return the resolved path.
from_toml	Load a config from a TOML string or file path.
inspect	Render the nested configuration as a Rich tree on the project console.

1.5.1.2.1 setup_target

utils.BaseConfig.setup_target(*args, **kwargs)

Instantiate or return the target object for this config, if applicable.

Prioritizes a ‘setup_target’ method on the target itself and falls back to calling the init method.

1.5.1.2.2 settings_customise_sources

utils.BaseConfig.settings_customise_sources(
    settings_cls,
    init_settings,
    env_settings,
    dotenv_settings,
    file_secret_settings,
)

Restrict default settings sources to init + optional TOML/CLI.

By default, environment/dotenv/file-secret sources are disabled for safety. Classes can opt into CLI by setting cli_parse_args=True in model_config or override this method for custom behavior.

1.5.1.2.3 model_dump_jsonable

utils.BaseConfig.model_dump_jsonable(**kwargs)

Return a JSON-serializable dump suitable for logging/checkpoint metadata.

1.5.1.2.4 model_dump_cache

utils.BaseConfig.model_dump_cache(exclude=None, exclude_none=True)

Return a cache-friendly dump with per-field cache exclusions.

1.5.1.2.4.1 Parameters

Name	Type	Description	Default
exclude	set[str] \| None	Additional field names to exclude from the snapshot.	`None`
exclude_none	bool	Skip fields with value `None` when True.	`True`

1.5.1.2.5 to_jsonable

utils.BaseConfig.to_jsonable(value)

Convert nested configs and common types into JSON-friendly primitives.

1.5.1.2.6 to_toml

utils.BaseConfig.to_toml(
    path=None,
    *,
    include_comments=True,
    include_type_hints=True,
)

Serialise the config (and nested configs) to TOML.

1.5.1.2.6.1 Parameters

Name	Type	Description	Default
path	Path \| None	Optional path to write the TOML to.	`None`
include_comments	bool	Ignored (kept for API compatibility).	`True`
include_type_hints	bool	Ignored (kept for API compatibility).	`True`

1.5.1.2.6.2 Returns

Name	Type	Description
	str	The rendered TOML string.

1.5.1.2.7 save_toml

utils.BaseConfig.save_toml(
    path,
    *,
    include_comments=True,
    include_type_hints=True,
)

Persist the configuration to a TOML file and return the resolved path.

1.5.1.2.8 from_toml

utils.BaseConfig.from_toml(source)

Load a config from a TOML string or file path.

1.5.1.2.9 inspect

utils.BaseConfig.inspect(show_docs=False)

Render the nested configuration as a Rich tree on the project console.

1.5.1.2.9.1 Parameters

Name	Type	Description	Default
show_docs	bool	Include class and field documentation alongside values.	`False`

1.5.2 Console

utils.Console(**kwargs)

Console wrapper that centralises formatting and convenience helpers.

1.5.2.1 Attributes

Name	Description
prefix	Instance-local `::`-separated source context prepended to messages.
verbosity	Return the process-wide minimum level for informational output.
verbose	Report whether normal informational logging is currently enabled.
is_debug	Return the process-wide debug gate used by :meth:`dbg`.

1.5.2.2 Methods

Name	Description
with_prefix	Create a console instance with a prefixed context.
with_caller_prefix	Create a console with prefix inferred from the caller’s module and function.
from_callsite	Compatibility constructor mirroring the PRML VSLAM console API.
set_prefix	Set a custom prefix for all log messages.
unset_prefix	Remove this instance’s contextual prefix and return the console.
log	Emit an informational message when verbosity is enabled.
log_summary	Log a structured summary built from `summarize`.
warn	Emit a warning message and include a short caller stack.
error	Emit an error message and show the relevant caller stack.
plog	Pretty-print an object using the best available formatter.
dbg	Emit a debug message when debug mode is enabled.
dbg_summary	Emit a compact tensor-aware summary when debug logging is enabled.
set_verbosity	Set verbosity level (0=quiet, 1=normal, 2=verbose).
set_verbose	Backward-compatible alias for `set_verbosity`.
set_debug	Enable or disable debug logging while keeping verbose mode sensible.
set_timestamp_display	Toggle timestamps for subsequent log messages.
integrate_with_logger	Integrate all Console instances with PyTorch Lightning logger for WandB/TensorBoard logging.
update_global_step	Update the shared global step for all console instances.
capture_sink	Observe log lines in the current execution context.

1.5.2.2.1 with_prefix

utils.Console.with_prefix(*parts)

Create a console instance with a prefixed context.

Enables builder-style chaining.

Usage:

console = Console.with_prefix(
    self.__class__.__name__,
    <name_of_the_current_method>
    <further_parts>, # eg. stage, worker_idx...
)

1.5.2.2.2 with_caller_prefix

utils.Console.with_caller_prefix(*extra_parts, stack_depth=1)

Create a console with prefix inferred from the caller’s module and function.

1.5.2.2.3 from_callsite

utils.Console.from_callsite(*parts, stack_offset=0)

Compatibility constructor mirroring the PRML VSLAM console API.

1.5.2.2.4 set_prefix

utils.Console.set_prefix(*parts)

Set a custom prefix for all log messages.

Enables builder-style chaining.

1.5.2.2.5 unset_prefix

utils.Console.unset_prefix()

Remove this instance’s contextual prefix and return the console.

1.5.2.2.6 log

utils.Console.log(message)

Emit an informational message when verbosity is enabled.

1.5.2.2.7 log_summary

utils.Console.log_summary(label, value, *, include_stats=False)

Log a structured summary built from summarize.

1.5.2.2.8 warn

utils.Console.warn(message)

Emit a warning message and include a short caller stack.

1.5.2.2.9 error

utils.Console.error(message)

Emit an error message and show the relevant caller stack.

1.5.2.2.10 plog

utils.Console.plog(obj, **kwargs)

Pretty-print an object using the best available formatter.

1.5.2.2.11 dbg

utils.Console.dbg(message)

Emit a debug message when debug mode is enabled.

1.5.2.2.12 dbg_summary

utils.Console.dbg_summary(label, value, *, include_stats=False)

Emit a compact tensor-aware summary when debug logging is enabled.

1.5.2.2.13 set_verbosity

utils.Console.set_verbosity(level)

Set verbosity level (0=quiet, 1=normal, 2=verbose).

1.5.2.2.14 set_verbose

utils.Console.set_verbose(verbose)

Backward-compatible alias for set_verbosity.

1.5.2.2.15 set_debug

utils.Console.set_debug(is_debug)

Enable or disable debug logging while keeping verbose mode sensible.

1.5.2.2.16 set_timestamp_display

utils.Console.set_timestamp_display(show_timestamps)

Toggle timestamps for subsequent log messages.

1.5.2.2.17 integrate_with_logger

utils.Console.integrate_with_logger(logger, global_step=0)

Integrate all Console instances with PyTorch Lightning logger for WandB/TensorBoard logging.

This is a class method that sets the shared logger state for all Console instances.

1.5.2.2.17.1 Parameters

Name	Type	Description	Default
logger	Logger	PyTorch Lightning logger instance (e.g., WandbLogger, TensorBoardLogger).	required
global_step	int	Current training step for metric logging.	`0`

1.5.2.2.17.2 Returns

Name	Type	Description
	type[Console]	Console class for method chaining.

1.5.2.2.17.3 Example

# In your LightningModule.__init__
Console.integrate_with_logger(self.logger)

# In training_step
def training_step(self, batch, batch_idx):
    Console.update_global_step(self.global_step)
    console = Console.with_prefix("training")
    console.log("Processing batch")  # → Terminal + WandB!

1.5.2.2.18 update_global_step

utils.Console.update_global_step(global_step)

Update the shared global step for all console instances.

1.5.2.2.19 capture_sink

utils.Console.capture_sink(sink)

Observe log lines in the current execution context.

Nested and concurrent contexts remain isolated. The previous observer is restored even when the observed operation raises.

1.5.3 Optimizable

utils.Optimizable()

Declarative description of an optimisable parameter.

The class intentionally avoids importing Optuna at runtime so the rest of the package can be used without the optional dependency. The trial argument is treated duck-typed (expects suggest_float/int/categorical methods).

1.5.3.1 Attributes

Name	Description
target	Type of the parameter (int, float, bool, str, Enum).
low	Lower bound for numeric spaces.
high	Upper bound for numeric spaces.
step	Step used for discrete integer suggestions.
categories	Explicit set of categorical choices (or Enum members).
log	Use logarithmic sampling for numeric spaces.
name	Optional override for the Optuna parameter name.
default	Default value used outside Optuna trials.
description	Human readable description of the parameter.
relies_on	Optional dependency map: {param_path: (accepted_values,…)}.

1.5.3.2 Methods

Name	Description
continuous	Describe a bounded floating-point search space.
discrete	Describe a bounded integer search space with a fixed step.
categorical	Describe a search space over an explicit finite choice set.
suggest	Sample a value from Optuna.
serialize	Convert a suggested value to a JSON/W&B friendly representation.

1.5.3.2.1 continuous

utils.Optimizable.continuous(
    low,
    high,
    log=False,
    name=None,
    default=None,
    description=None,
    relies_on=None,
)

Describe a bounded floating-point search space.

1.5.3.2.2 discrete

utils.Optimizable.discrete(
    low,
    high,
    step=1,
    log=False,
    name=None,
    default=None,
    description=None,
    relies_on=None,
)

Describe a bounded integer search space with a fixed step.

1.5.3.2.3 categorical

utils.Optimizable.categorical(
    choices,
    name=None,
    default=None,
    description=None,
    relies_on=None,
)

Describe a search space over an explicit finite choice set.

1.5.3.2.4 suggest

utils.Optimizable.suggest(trial, path, *, current_value=None, value_lookup=None)

Sample a value from Optuna.

1.5.3.2.4.1 Parameters

Name	Type	Description	Default
trial	'optuna.Trial'	Optuna trial (duck-typed; must implement suggest_* APIs).	required
path	str	Default parameter name derived from the config path.	required

1.5.3.2.4.2 Returns

Name	Type	Description
	`T`	Suggested value coerced into the requested target type.

1.5.3.2.5 serialize

utils.Optimizable.serialize(value)

Convert a suggested value to a JSON/W&B friendly representation.

1.5.4 SingletonConfig

utils.SingletonConfig(**kwargs)

Base class for singleton configurations.

1.5.5 Stage

utils.Stage()

Stages of the training lifecycle.

1.5.5.1 Members

TRAIN: “train” VAL: “val” TEST: “test”

1.5.5.2 Methods

Name	Description
from_str	Map strings (e.g. “fit”, “validate”) back to Stage members.

1.5.5.2.1 from_str

utils.Stage.from_str(value)

Map strings (e.g. “fit”, “validate”) back to Stage members.

1.5.6 TargetConfig

utils.TargetConfig()

Typed config-as-factory base whose setup_target returns TargetT.

TargetT describes the runtime object returned by setup_target; it does not have to be the same type as target_type when the target delegates to a custom factory method.

1.5.6.1 Methods

Name	Description
setup_target	Instantiate or return the typed target object for this config.

1.5.6.1.1 setup_target

utils.TargetConfig.setup_target(*args, **kwargs)

Instantiate or return the typed target object for this config.

1.5.7 ValueStrEnum

utils.ValueStrEnum()

StrEnum variant whose string form is always its underlying value.

1.5.8 Verbosity

utils.Verbosity()

Ordered output gates shared by every Console instance.

1.5.8.1 Methods

Name	Description
from_any	Coerce booleans/ints/strings into a Verbosity level.

1.5.8.1.1 from_any

utils.Verbosity.from_any(value)

Coerce booleans/ints/strings into a Verbosity level.

1.6 Functions

Name	Description
optimizable_field	Attach an optimizable definition to a Pydantic Field.
rotate_yaw_cw90	Rotate a pose by 90° clockwise about its local +Z axis.

1.6.1 optimizable_field

utils.optimizable_field(
    default=None,
    default_factory=None,
    optimizable,
    **field_kwargs,
)

Attach an optimizable definition to a Pydantic Field.

Exactly one of default or default_factory must be provided.

1.6.2 rotate_yaw_cw90

utils.rotate_yaw_cw90(pose_world_cam, undo=False)

Rotate a pose by 90° clockwise about its local +Z axis.

1.6.2.1 Important

Despite the historical name, this is a local-frame rotation (right-multiplication) about the pose’s +Z axis. In the Aria LUF convention (+Z = forward), this is a roll/twist that swaps the local +X/+Y axes.

1.6.2.2 Why this exists

Project Aria tooling/visualisations sometimes apply a fixed 90° twist for display.
In our candidate generation pipeline we also apply this to the reference pose as a rig-basis correction so that sampling assumptions (LUF: x=left, y=up, z=fwd) match the incoming t_world_rig basis (otherwise azimuth/elevation look swapped).

1.6.2.3 Caution

Apply this conversion at most once in any given path; applying it again in plotting will look like an azimuth/elevation swap once roll jitter is enabled.

# utils { #aria_nbv.utils } `utils` Stable cross-domain configuration, stage, console, and geometry contracts. Specialized formatting, summaries, serialization, and domain semantics live in explicit owner leaves instead of expanding this package-root interface.  ## Package guide `aria_nbv.utils` contains small cross-domain runtime contracts. The package root is intentionally narrow: configuration factories, `Console`/`Verbosity`, training `Stage`, optimization markers, and the established yaw helper remain available there. Formatting, serialization, and diagnostic details use their own explicit leaves. ## Owners - `console/` owns process-wide console state, tensor-aware summaries, reusable Rich formatting, and the shared Typer runner. Its package marker exposes only `Console` and `Verbosity`; consumers import summaries, formatting, and CLI execution from their named leaves. - `tensor_payloads.py` converts tensors, EFM wrappers, and PyTorch3D cameras to CPU msgspec payloads and reconstructs them on an explicit device. - `stages.py` owns stable string serialization for `Stage` and `ValueStrEnum`. - `plotting/snippet.py` owns complete 3D EFM snippet figures: pose and semidense selection, mesh/box traces, trajectory bounds, and Plotly frusta. - `plotting/grids.py` owns image grids, frame overlays, scalar-field slices, and histogram primitives. Tensor inputs are detached and moved to CPU at this presentation seam. - `plotting/benchmarks.py` owns paired Python/Mojo benchmark ingestion, within-stratum summaries, figures, and report persistence. - `fingerprints.py`, `metric_reductions.py`, and `seeding.py` remain narrow behavior owners shared by multiple scientific packages. ASE/EFM semantic names live in `aria_nbv.data_handling.ase_efm.semantics`; identifier parsing lives in `aria_nbv.data_handling.identifiers`. Experiment tracking belongs to [`reporting/wandb`](reporting.wandb.qmd); frame geometry and gradient logging have their own domain owners. Configuration construction, path resolution and optimization markers belong to [`configs`](configs.qmd); their established utility-root imports load lazily to preserve compatibility without reversing the dependency. The snippet frustum kernel intentionally remains with snippet presentation. It uses normalized rays through an inscribed valid-radius square. Rerun frusta use image corners at camera-z depth, so merging them would erase a real rendering policy difference rather than remove duplication. ## Usage ```python from aria_nbv.utils import Console, Stage from aria_nbv.utils.console.summary import summarize from aria_nbv.utils.plotting.benchmarks import load_benchmark_csv from aria_nbv.utils.plotting.snippet import SnippetPlotBuilder from aria_nbv.utils.tensor_payloads import to_serializable Console.with_prefix("loader").log_summary("batch", summarize(batch)) payload = to_serializable(batch) assert Stage.from_str("validate") is Stage.VAL ``` Import plotting behavior from its named leaf. The `plotting` package marker is navigation only and does not re-export every builder or primitive. The console root import is supported. Former flat formatting and summary module paths are intentionally unsupported after internal consumers migrate; no forwarding modules recreate that surface. ## Verification From `aria_nbv/` run: ```sh uv run pytest tests/test_console.py tests/utils/test_rich_summary.py uv run pytest tests/data_handling/test_utils.py tests/vin/test_backbone_evl.py uv run pytest tests/rollouts/test_cli_typer.py uv run pytest tests/test_plotting_helpers_refactor.py \ tests/test_plotting_frustum_device.py tests/utils/test_plotting_utils.py \ tests/utils/test_benchmark_plotting.py uv run ruff check aria_nbv/utils aria_nbv/data_handling/identifiers.py ```  ## Classes | Name | Description | | --- | --- | | [BaseConfig](#aria_nbv.utils.BaseConfig) | Validate, serialize, inspect, and instantiate one configuration tree. | | [Console](#aria_nbv.utils.Console) | Console wrapper that centralises formatting and convenience helpers. | | [Optimizable](#aria_nbv.utils.Optimizable) | Declarative description of an optimisable parameter. | | [SingletonConfig](#aria_nbv.utils.SingletonConfig) | Base class for singleton configurations. | | [Stage](#aria_nbv.utils.Stage) | Stages of the training lifecycle. | | [TargetConfig](#aria_nbv.utils.TargetConfig) | Typed config-as-factory base whose `setup_target` returns `TargetT`. | | [ValueStrEnum](#aria_nbv.utils.ValueStrEnum) | StrEnum variant whose string form is always its underlying value. | | [Verbosity](#aria_nbv.utils.Verbosity) | Ordered output gates shared by every :class:`Console` instance. | ### BaseConfig { #aria_nbv.utils.BaseConfig } ```python utils.BaseConfig() ``` Validate, serialize, inspect, and instantiate one configuration tree. Subclasses that construct runtime objects should inherit :class:`TargetConfig` and expose `target_type`. Plain subclasses may use `setup_target` as a no-op and still share TOML, cache, and CLI behavior. #### Attributes | Name | Description | | --- | --- | | [cache_exclude_fields](#aria_nbv.utils.BaseConfig.cache_exclude_fields) | Field names to exclude from cache snapshots. | | [cache_exclude_extra_key](#aria_nbv.utils.BaseConfig.cache_exclude_extra_key) | json_schema_extra key for marking fields excluded from cache snapshots. | | [propagation_exclude_fields](#aria_nbv.utils.BaseConfig.propagation_exclude_fields) | Field names that must not propagate into nested config identities. | | [target_type](#aria_nbv.utils.BaseConfig.target_type) | Callable target used by `setup_target`. | | [target](#aria_nbv.utils.BaseConfig.target) | Compatibility alias for `target_type`. | | [propagated_fields](#aria_nbv.utils.BaseConfig.propagated_fields) | Track which fields were propagated from a parent config. | #### Methods | Name | Description | | --- | --- | | [setup_target](#aria_nbv.utils.BaseConfig.setup_target) | Instantiate or return the target object for this config, if applicable. | | [settings_customise_sources](#aria_nbv.utils.BaseConfig.settings_customise_sources) | Restrict default settings sources to init + optional TOML/CLI. | | [model_dump_jsonable](#aria_nbv.utils.BaseConfig.model_dump_jsonable) | Return a JSON-serializable dump suitable for logging/checkpoint metadata. | | [model_dump_cache](#aria_nbv.utils.BaseConfig.model_dump_cache) | Return a cache-friendly dump with per-field cache exclusions. | | [to_jsonable](#aria_nbv.utils.BaseConfig.to_jsonable) | Convert nested configs and common types into JSON-friendly primitives. | | [to_toml](#aria_nbv.utils.BaseConfig.to_toml) | Serialise the config (and nested configs) to TOML. | | [save_toml](#aria_nbv.utils.BaseConfig.save_toml) | Persist the configuration to a TOML file and return the resolved path. | | [from_toml](#aria_nbv.utils.BaseConfig.from_toml) | Load a config from a TOML string or file path. | | [inspect](#aria_nbv.utils.BaseConfig.inspect) | Render the nested configuration as a Rich tree on the project console. | ##### setup_target { #aria_nbv.utils.BaseConfig.setup_target } ```python utils.BaseConfig.setup_target(*args, **kwargs) ``` Instantiate or return the target object for this config, if applicable. Prioritizes a 'setup_target' method on the target itself and falls back to calling the init method. ##### settings_customise_sources { #aria_nbv.utils.BaseConfig.settings_customise_sources } ```python utils.BaseConfig.settings_customise_sources( settings_cls, init_settings, env_settings, dotenv_settings, file_secret_settings, ) ``` Restrict default settings sources to init + optional TOML/CLI. By default, environment/dotenv/file-secret sources are disabled for safety. Classes can opt into CLI by setting `cli_parse_args=True` in model_config or override this method for custom behavior. ##### model_dump_jsonable { #aria_nbv.utils.BaseConfig.model_dump_jsonable } ```python utils.BaseConfig.model_dump_jsonable(**kwargs) ``` Return a JSON-serializable dump suitable for logging/checkpoint metadata. ##### model_dump_cache { #aria_nbv.utils.BaseConfig.model_dump_cache } ```python utils.BaseConfig.model_dump_cache(exclude=None, exclude_none=True) ``` Return a cache-friendly dump with per-field cache exclusions. ###### Parameters {.doc-section .doc-section-parameters} | Name | Type | Description | Default | |--------------|--------------------------------------|------------------------------------------------------|-----------| | exclude | [set](`set`)\[[str](`str`)\] \| None | Additional field names to exclude from the snapshot. | `None` | | exclude_none | [bool](`bool`) | Skip fields with value ``None`` when True. | `True` | ##### to_jsonable { #aria_nbv.utils.BaseConfig.to_jsonable } ```python utils.BaseConfig.to_jsonable(value) ``` Convert nested configs and common types into JSON-friendly primitives. ##### to_toml { #aria_nbv.utils.BaseConfig.to_toml } ```python utils.BaseConfig.to_toml( path=None, *, include_comments=True, include_type_hints=True, ) ``` Serialise the config (and nested configs) to TOML. ###### Parameters {.doc-section .doc-section-parameters} | Name | Type | Description | Default | |--------------------|--------------------------------|---------------------------------------|-----------| | path | [Path](`pathlib.Path`) \| None | Optional path to write the TOML to. | `None` | | include_comments | [bool](`bool`) | Ignored (kept for API compatibility). | `True` | | include_type_hints | [bool](`bool`) | Ignored (kept for API compatibility). | `True` | ###### Returns {.doc-section .doc-section-returns} | Name | Type | Description | |--------|--------------|---------------------------| | | [str](`str`) | The rendered TOML string. | ##### save_toml { #aria_nbv.utils.BaseConfig.save_toml } ```python utils.BaseConfig.save_toml( path, *, include_comments=True, include_type_hints=True, ) ``` Persist the configuration to a TOML file and return the resolved path. ##### from_toml { #aria_nbv.utils.BaseConfig.from_toml } ```python utils.BaseConfig.from_toml(source) ``` Load a config from a TOML string or file path. ##### inspect { #aria_nbv.utils.BaseConfig.inspect } ```python utils.BaseConfig.inspect(show_docs=False) ``` Render the nested configuration as a Rich tree on the project console. ###### Parameters {.doc-section .doc-section-parameters} | Name | Type | Description | Default | |-----------|----------------|---------------------------------------------------------|-----------| | show_docs | [bool](`bool`) | Include class and field documentation alongside values. | `False` | ### Console { #aria_nbv.utils.Console } ```python utils.Console(**kwargs) ``` Console wrapper that centralises formatting and convenience helpers. #### Attributes | Name | Description | | --- | --- | | [prefix](#aria_nbv.utils.Console.prefix) | Instance-local `::`-separated source context prepended to messages. | | [verbosity](#aria_nbv.utils.Console.verbosity) | Return the process-wide minimum level for informational output. | | [verbose](#aria_nbv.utils.Console.verbose) | Report whether normal informational logging is currently enabled. | | [is_debug](#aria_nbv.utils.Console.is_debug) | Return the process-wide debug gate used by :meth:`dbg`. | #### Methods | Name | Description | | --- | --- | | [with_prefix](#aria_nbv.utils.Console.with_prefix) | Create a console instance with a prefixed context. | | [with_caller_prefix](#aria_nbv.utils.Console.with_caller_prefix) | Create a console with prefix inferred from the caller's module and function. | | [from_callsite](#aria_nbv.utils.Console.from_callsite) | Compatibility constructor mirroring the PRML VSLAM console API. | | [set_prefix](#aria_nbv.utils.Console.set_prefix) | Set a custom prefix for all log messages. | | [unset_prefix](#aria_nbv.utils.Console.unset_prefix) | Remove this instance's contextual prefix and return the console. | | [log](#aria_nbv.utils.Console.log) | Emit an informational message when verbosity is enabled. | | [log_summary](#aria_nbv.utils.Console.log_summary) | Log a structured summary built from `summarize`. | | [warn](#aria_nbv.utils.Console.warn) | Emit a warning message and include a short caller stack. | | [error](#aria_nbv.utils.Console.error) | Emit an error message and show the relevant caller stack. | | [plog](#aria_nbv.utils.Console.plog) | Pretty-print an object using the best available formatter. | | [dbg](#aria_nbv.utils.Console.dbg) | Emit a debug message when debug mode is enabled. | | [dbg_summary](#aria_nbv.utils.Console.dbg_summary) | Emit a compact tensor-aware summary when debug logging is enabled. | | [set_verbosity](#aria_nbv.utils.Console.set_verbosity) | Set verbosity level (0=quiet, 1=normal, 2=verbose). | | [set_verbose](#aria_nbv.utils.Console.set_verbose) | Backward-compatible alias for `set_verbosity`. | | [set_debug](#aria_nbv.utils.Console.set_debug) | Enable or disable debug logging while keeping verbose mode sensible. | | [set_timestamp_display](#aria_nbv.utils.Console.set_timestamp_display) | Toggle timestamps for subsequent log messages. | | [integrate_with_logger](#aria_nbv.utils.Console.integrate_with_logger) | Integrate all Console instances with PyTorch Lightning logger for WandB/TensorBoard logging. | | [update_global_step](#aria_nbv.utils.Console.update_global_step) | Update the shared global step for all console instances. | | [capture_sink](#aria_nbv.utils.Console.capture_sink) | Observe log lines in the current execution context. | ##### with_prefix { #aria_nbv.utils.Console.with_prefix } ```python utils.Console.with_prefix(*parts) ``` Create a console instance with a prefixed context. Enables builder-style chaining. Usage: ```python console = Console.with_prefix( self.__class__.__name__, <name_of_the_current_method> <further_parts>, # eg. stage, worker_idx... ) ``` ##### with_caller_prefix { #aria_nbv.utils.Console.with_caller_prefix } ```python utils.Console.with_caller_prefix(*extra_parts, stack_depth=1) ``` Create a console with prefix inferred from the caller's module and function. ##### from_callsite { #aria_nbv.utils.Console.from_callsite } ```python utils.Console.from_callsite(*parts, stack_offset=0) ``` Compatibility constructor mirroring the PRML VSLAM console API. ##### set_prefix { #aria_nbv.utils.Console.set_prefix } ```python utils.Console.set_prefix(*parts) ``` Set a custom prefix for all log messages. Enables builder-style chaining. ##### unset_prefix { #aria_nbv.utils.Console.unset_prefix } ```python utils.Console.unset_prefix() ``` Remove this instance's contextual prefix and return the console. ##### log { #aria_nbv.utils.Console.log } ```python utils.Console.log(message) ``` Emit an informational message when verbosity is enabled. ##### log_summary { #aria_nbv.utils.Console.log_summary } ```python utils.Console.log_summary(label, value, *, include_stats=False) ``` Log a structured summary built from `summarize`. ##### warn { #aria_nbv.utils.Console.warn } ```python utils.Console.warn(message) ``` Emit a warning message and include a short caller stack. ##### error { #aria_nbv.utils.Console.error } ```python utils.Console.error(message) ``` Emit an error message and show the relevant caller stack. ##### plog { #aria_nbv.utils.Console.plog } ```python utils.Console.plog(obj, **kwargs) ``` Pretty-print an object using the best available formatter. ##### dbg { #aria_nbv.utils.Console.dbg } ```python utils.Console.dbg(message) ``` Emit a debug message when debug mode is enabled. ##### dbg_summary { #aria_nbv.utils.Console.dbg_summary } ```python utils.Console.dbg_summary(label, value, *, include_stats=False) ``` Emit a compact tensor-aware summary when debug logging is enabled. ##### set_verbosity { #aria_nbv.utils.Console.set_verbosity } ```python utils.Console.set_verbosity(level) ``` Set verbosity level (0=quiet, 1=normal, 2=verbose). ##### set_verbose { #aria_nbv.utils.Console.set_verbose } ```python utils.Console.set_verbose(verbose) ``` Backward-compatible alias for `set_verbosity`. ##### set_debug { #aria_nbv.utils.Console.set_debug } ```python utils.Console.set_debug(is_debug) ``` Enable or disable debug logging while keeping verbose mode sensible. ##### set_timestamp_display { #aria_nbv.utils.Console.set_timestamp_display } ```python utils.Console.set_timestamp_display(show_timestamps) ``` Toggle timestamps for subsequent log messages. ##### integrate_with_logger { #aria_nbv.utils.Console.integrate_with_logger } ```python utils.Console.integrate_with_logger(logger, global_step=0) ``` Integrate all Console instances with PyTorch Lightning logger for WandB/TensorBoard logging. This is a class method that sets the shared logger state for all Console instances. ###### Parameters {.doc-section .doc-section-parameters} | Name | Type | Description | Default | |-------------|-----------------------------------------------------|---------------------------------------------------------------------------|------------| | logger | [Logger](`lightning.pytorch.loggers.logger.Logger`) | PyTorch Lightning logger instance (e.g., WandbLogger, TensorBoardLogger). | _required_ | | global_step | [int](`int`) | Current training step for metric logging. | `0` | ###### Returns {.doc-section .doc-section-returns} | Name | Type | Description | |--------|-----------------------------------------------------------------------|------------------------------------| | | [type](`type`)\[[Console](`aria_nbv.utils.console.logging.Console`)\] | Console class for method chaining. | ###### Example {.doc-section .doc-section-example} ```python # In your LightningModule.__init__ Console.integrate_with_logger(self.logger) # In training_step def training_step(self, batch, batch_idx): Console.update_global_step(self.global_step) console = Console.with_prefix("training") console.log("Processing batch") # → Terminal + WandB! ``` ##### update_global_step { #aria_nbv.utils.Console.update_global_step } ```python utils.Console.update_global_step(global_step) ``` Update the shared global step for all console instances. ##### capture_sink { #aria_nbv.utils.Console.capture_sink } ```python utils.Console.capture_sink(sink) ``` Observe log lines in the current execution context. Nested and concurrent contexts remain isolated. The previous observer is restored even when the observed operation raises. ### Optimizable { #aria_nbv.utils.Optimizable } ```python utils.Optimizable() ``` Declarative description of an optimisable parameter. The class intentionally avoids importing Optuna at runtime so the rest of the package can be used without the optional dependency. The ``trial`` argument is treated duck-typed (expects ``suggest_float/int/categorical`` methods). #### Attributes | Name | Description | | --- | --- | | [target](#aria_nbv.utils.Optimizable.target) | Type of the parameter (int, float, bool, str, Enum). | | [low](#aria_nbv.utils.Optimizable.low) | Lower bound for numeric spaces. | | [high](#aria_nbv.utils.Optimizable.high) | Upper bound for numeric spaces. | | [step](#aria_nbv.utils.Optimizable.step) | Step used for discrete integer suggestions. | | [categories](#aria_nbv.utils.Optimizable.categories) | Explicit set of categorical choices (or Enum members). | | [log](#aria_nbv.utils.Optimizable.log) | Use logarithmic sampling for numeric spaces. | | [name](#aria_nbv.utils.Optimizable.name) | Optional override for the Optuna parameter name. | | [default](#aria_nbv.utils.Optimizable.default) | Default value used outside Optuna trials. | | [description](#aria_nbv.utils.Optimizable.description) | Human readable description of the parameter. | | [relies_on](#aria_nbv.utils.Optimizable.relies_on) | Optional dependency map: {param_path: (accepted_values,...)}. | #### Methods | Name | Description | | --- | --- | | [continuous](#aria_nbv.utils.Optimizable.continuous) | Describe a bounded floating-point search space. | | [discrete](#aria_nbv.utils.Optimizable.discrete) | Describe a bounded integer search space with a fixed step. | | [categorical](#aria_nbv.utils.Optimizable.categorical) | Describe a search space over an explicit finite choice set. | | [suggest](#aria_nbv.utils.Optimizable.suggest) | Sample a value from Optuna. | | [serialize](#aria_nbv.utils.Optimizable.serialize) | Convert a suggested value to a JSON/W&B friendly representation. | ##### continuous { #aria_nbv.utils.Optimizable.continuous } ```python utils.Optimizable.continuous( low, high, log=False, name=None, default=None, description=None, relies_on=None, ) ``` Describe a bounded floating-point search space. ##### discrete { #aria_nbv.utils.Optimizable.discrete } ```python utils.Optimizable.discrete( low, high, step=1, log=False, name=None, default=None, description=None, relies_on=None, ) ``` Describe a bounded integer search space with a fixed step. ##### categorical { #aria_nbv.utils.Optimizable.categorical } ```python utils.Optimizable.categorical( choices, name=None, default=None, description=None, relies_on=None, ) ``` Describe a search space over an explicit finite choice set. ##### suggest { #aria_nbv.utils.Optimizable.suggest } ```python utils.Optimizable.suggest(trial, path, *, current_value=None, value_lookup=None) ``` Sample a value from Optuna. ###### Parameters {.doc-section .doc-section-parameters} | Name | Type | Description | Default | |--------|------------------|-----------------------------------------------------------|------------| | trial | \'optuna.Trial\' | Optuna trial (duck-typed; must implement suggest_* APIs). | _required_ | | path | [str](`str`) | Default parameter name derived from the config path. | _required_ | ###### Returns {.doc-section .doc-section-returns} | Name | Type | Description | |--------|---------------------------------------|---------------------------------------------------------| | | [T](`aria_nbv.configs.optimizable.T`) | Suggested value coerced into the requested target type. | ##### serialize { #aria_nbv.utils.Optimizable.serialize } ```python utils.Optimizable.serialize(value) ``` Convert a suggested value to a JSON/W&B friendly representation. ### SingletonConfig { #aria_nbv.utils.SingletonConfig } ```python utils.SingletonConfig(**kwargs) ``` Base class for singleton configurations. ### Stage { #aria_nbv.utils.Stage } ```python utils.Stage() ``` Stages of the training lifecycle. #### Members {.doc-section .doc-section-members} TRAIN: "train" VAL: "val" TEST: "test" #### Methods | Name | Description | | --- | --- | | [from_str](#aria_nbv.utils.Stage.from_str) | Map strings (e.g. "fit", "validate") back to Stage members. | ##### from_str { #aria_nbv.utils.Stage.from_str } ```python utils.Stage.from_str(value) ``` Map strings (e.g. "fit", "validate") back to Stage members. ### TargetConfig { #aria_nbv.utils.TargetConfig } ```python utils.TargetConfig() ``` Typed config-as-factory base whose `setup_target` returns `TargetT`. `TargetT` describes the runtime object returned by `setup_target`; it does not have to be the same type as `target_type` when the target delegates to a custom factory method. #### Methods | Name | Description | | --- | --- | | [setup_target](#aria_nbv.utils.TargetConfig.setup_target) | Instantiate or return the typed target object for this config. | ##### setup_target { #aria_nbv.utils.TargetConfig.setup_target } ```python utils.TargetConfig.setup_target(*args, **kwargs) ``` Instantiate or return the typed target object for this config. ### ValueStrEnum { #aria_nbv.utils.ValueStrEnum } ```python utils.ValueStrEnum() ``` StrEnum variant whose string form is always its underlying value. ### Verbosity { #aria_nbv.utils.Verbosity } ```python utils.Verbosity() ``` Ordered output gates shared by every :class:`Console` instance. #### Methods | Name | Description | | --- | --- | | [from_any](#aria_nbv.utils.Verbosity.from_any) | Coerce booleans/ints/strings into a Verbosity level. | ##### from_any { #aria_nbv.utils.Verbosity.from_any } ```python utils.Verbosity.from_any(value) ``` Coerce booleans/ints/strings into a Verbosity level. ## Functions | Name | Description | | --- | --- | | [optimizable_field](#aria_nbv.utils.optimizable_field) | Attach an optimizable definition to a Pydantic Field. | | [rotate_yaw_cw90](#aria_nbv.utils.rotate_yaw_cw90) | Rotate a pose by 90° clockwise about its **local +Z axis**. | ### optimizable_field { #aria_nbv.utils.optimizable_field } ```python utils.optimizable_field( default=None, default_factory=None, optimizable, **field_kwargs, ) ``` Attach an optimizable definition to a Pydantic Field. Exactly one of ``default`` or ``default_factory`` must be provided. ### rotate_yaw_cw90 { #aria_nbv.utils.rotate_yaw_cw90 } ```python utils.rotate_yaw_cw90(pose_world_cam, undo=False) ``` Rotate a pose by 90° clockwise about its **local +Z axis**. #### Important {.doc-section .doc-section-important} Despite the historical name, this is a *local-frame* rotation (right-multiplication) about the pose's +Z axis. In the Aria LUF convention (+Z = forward), this is a **roll/twist** that swaps the local +X/+Y axes. #### Why this exists {.doc-section .doc-section-why-this-exists} - Project Aria tooling/visualisations sometimes apply a fixed 90° twist for display. - In our candidate generation pipeline we also apply this to the **reference pose** as a rig-basis correction so that sampling assumptions (LUF: x=left, y=up, z=fwd) match the incoming `t_world_rig` basis (otherwise azimuth/elevation look swapped). #### Caution {.doc-section .doc-section-caution} Apply this conversion **at most once** in any given path; applying it again in plotting will look like an azimuth/elevation swap once roll jitter is enabled.