1 configs.path_config

configs.path_config

Canonical filesystem locations and path-resolution policy.

This module owns PathConfig, singleton root discovery, and validation that rebases configured directories beneath the selected project/data roots. All project-relative paths are resolved against one singleton project root. Directory fields are created eagerly when permitted; file paths are resolved without fabricating missing artifacts so callers receive actionable errors. Dataset download, artifact contents, and domain-specific existence checks remain the responsibility of their consuming subsystems.

1.1 Classes

Name Description
PathConfig Centralize filesystem ownership for package, data, and run artifacts.

1.1.1 PathConfig

configs.path_config.PathConfig(**kwargs)

Centralize filesystem ownership for package, data, and run artifacts.

Reinitializing the singleton with a different root rebases fields that still equal their old root-derived defaults while preserving explicit overrides. Paths exposed by this config are absolute after validation.

1.1.1.1 Attributes

Name Description
root Absolute repository root used to resolve relative configuration paths.
data_root Root directory for all data (downloaded datasets, meshes, etc.).
data_root_massive Optional root directory for storing further large datasets, caches or artifacts.
checkpoints Directory used by Lightning checkpoints.
external_checkpoints Optional directory containing checkpoints produced outside this project.
wandb Directory used by Weights & Biases for local run artifacts.
optuna Directory used by Optuna for local study storage (SQLite).
configs_dir Directory containing exported experiment/configuration files (TOML, etc.).
url_dir Directory containing ASE download URL JSON files.
metadata_cache Path to cached ASE metadata JSON.
offline_cache_dir VIN offline-store directory, resolved below data_root_massive when set.
ase_meshes Directory for downloaded ASE ground truth meshes.
processed_meshes Directory for cropped/simplified meshes persisted for reuse.
external_dir Directory containing pinned external source checkouts such as EFM3D.

1.1.1.2 Methods

Name Description
resolve_checkpoint_path Resolve a checkpoint path relative to the checkpoints directory.
resolve_external_checkpoint_path Resolve and validate a checkpoint under external_checkpoints.
resolve_mesh_path Resolve path to GT mesh for a scene.
resolve_processed_mesh_path Resolve path for a processed (cropped/simplified) mesh artifact.
resolve_atek_data_dir Resolve path to ATEK data directory for a config.
get_atek_source_path Get path to vendored ATEK source.
get_atek_url_json_path Get path to ATEK download URLs JSON.
resolve_under_root Resolve a user-provided path relative to the project root.
resolve_cache_artifact_dir Resolve a cache or store directory against the configured data roots.
resolve_run_dir Resolve a run output directory and ensure it exists.
resolve_artifact_path Resolve an artifact file path under the project root.
resolve_config_toml_path Resolve a TOML experiment config path.
resolve_optuna_study_uri Resolve a SQLite Optuna storage URI for a given study name.
1.1.1.2.1 resolve_checkpoint_path
configs.path_config.PathConfig.resolve_checkpoint_path(path)

Resolve a checkpoint path relative to the checkpoints directory.

1.1.1.2.1.1 Parameters
Name Type Description Default
path str | Path | None Checkpoint path (absolute, relative, or None). required
1.1.1.2.1.2 Returns
Name Type Description
Path | None Resolved absolute path, or None if input is None/empty.
1.1.1.2.1.3 Raises
Name Type Description
FileNotFoundError If the resolved path does not exist.
1.1.1.2.2 resolve_external_checkpoint_path
configs.path_config.PathConfig.resolve_external_checkpoint_path(path)

Resolve and validate a checkpoint under external_checkpoints.

Absolute paths are accepted unchanged. Relative paths are interpreted below the configured external-checkpoint root and must already exist.

1.1.1.2.3 resolve_mesh_path
configs.path_config.PathConfig.resolve_mesh_path(scene_id)

Resolve path to GT mesh for a scene.

1.1.1.2.3.1 Parameters
Name Type Description Default
scene_id str Scene identifier (e.g., “82832”) required
1.1.1.2.3.2 Returns
Name Type Description
Path Path to mesh file (may not exist yet)
1.1.1.2.4 resolve_processed_mesh_path
configs.path_config.PathConfig.resolve_processed_mesh_path(
    scene_id,
    simplification_ratio,
    is_crop,
    spec_hash,
)

Resolve path for a processed (cropped/simplified) mesh artifact.

1.1.1.2.4.1 Parameters
Name Type Description Default
scene_id str ASE scene identifier. required
simplification_ratio float Mesh simplification ratio encoded in the filename. required
is_crop bool Whether the processed mesh is a cropped artifact. required
spec_hash str Short hash of the processing specification. required
1.1.1.2.4.2 Returns
Name Type Description
Path Destination path where the processed mesh should be stored.
1.1.1.2.5 resolve_atek_data_dir
configs.path_config.PathConfig.resolve_atek_data_dir(config_name='efm')

Resolve path to ATEK data directory for a config.

1.1.1.2.5.1 Parameters
Name Type Description Default
config_name str ATEK config name (e.g., “efm”, “efm_eval”) 'efm'
1.1.1.2.5.2 Returns
Name Type Description
Path Path to ATEK data directory
1.1.1.2.6 get_atek_source_path
configs.path_config.PathConfig.get_atek_source_path()

Get path to vendored ATEK source.

1.1.1.2.6.1 Returns
Name Type Description
Path Path to external/ATEK directory
1.1.1.2.6.2 Raises
Name Type Description
FileNotFoundError If ATEK is not found
1.1.1.2.7 get_atek_url_json_path
configs.path_config.PathConfig.get_atek_url_json_path(
    json_filename='AriaSyntheticEnvironment_ATEK_download_urls.json',
)

Get path to ATEK download URLs JSON.

1.1.1.2.7.1 Parameters
Name Type Description Default
json_filename str Name of the ATEK URL JSON file. 'AriaSyntheticEnvironment_ATEK_download_urls.json'
1.1.1.2.7.2 Returns
Name Type Description
Path Path to the ATEK URL JSON file.
1.1.1.2.8 resolve_under_root
configs.path_config.PathConfig.resolve_under_root(path, *, base_dir=None)

Resolve a user-provided path relative to the project root.

1.1.1.2.8.1 Parameters
Name Type Description Default
path str | Path Path to resolve (absolute or relative). required
base_dir Path | None Optional base directory to resolve relative paths against. Defaults to root. None
1.1.1.2.8.2 Returns
Name Type Description
Path Absolute, expanded, resolved path.
1.1.1.2.9 resolve_cache_artifact_dir
configs.path_config.PathConfig.resolve_cache_artifact_dir(path)

Resolve a cache or store directory against the configured data roots.

Relative paths default to offline_cache_dir when available and otherwise fall back to data_root. Paths that already start with the data-root or offline-cache root name are instead interpreted relative to root so callers can still pass repo-root-relative paths such as offline_cache/foo.

1.1.1.2.10 resolve_run_dir
configs.path_config.PathConfig.resolve_run_dir(out_dir)

Resolve a run output directory and ensure it exists.

1.1.1.2.11 resolve_artifact_path
configs.path_config.PathConfig.resolve_artifact_path(
    path,
    *,
    expected_suffix=None,
    create_parent=True,
)

Resolve an artifact file path under the project root.

1.1.1.2.11.1 Parameters
Name Type Description Default
path str | Path Path to resolve (absolute or relative). required
expected_suffix str | None Optional required suffix (e.g. “.json”, “.pt”, “.toml”). None
create_parent bool Create the parent directory when True. True
1.1.1.2.11.2 Returns
Name Type Description
Path Absolute, expanded, resolved path.
1.1.1.2.12 resolve_config_toml_path
configs.path_config.PathConfig.resolve_config_toml_path(
    path,
    *,
    must_exist=True,
)

Resolve a TOML experiment config path.

Relative paths are resolved as: - bare filenames (no parent) are interpreted as under configs_dir - other relative paths are interpreted as under root

1.1.1.2.13 resolve_optuna_study_uri
configs.path_config.PathConfig.resolve_optuna_study_uri(study_name)

Resolve a SQLite Optuna storage URI for a given study name.

Back to top