Environment Variables

Configure Archeo-Cluster using environment variables.

Archeo-Cluster reads a set of ARCHEO_* environment variables when no YAML config file is found. This makes it straightforward to configure the tool in containerized environments, CI pipelines, or any context where writing a config file is inconvenient.

Environment variables are only applied when no YAML config file is discovered during the directory traversal. If a config.yaml (or equivalent) is found, it takes full precedence and environment variables are not read.

Available environment variables

Detection

ARCHEO_TARGET_COLOR · string

Hex color code of the target object to detect. Maps to detection.target_color.

Default: #A98876

export ARCHEO_TARGET_COLOR="#8B6347"

ARCHEO_MIN_AREA · integer

Minimum contour area in pixels. Objects smaller than this value are discarded. Maps to detection.min_area.

Default: 50 — must be ≥ 1

export ARCHEO_MIN_AREA=100

ARCHEO_MAX_AREA · integer

Maximum contour area in pixels. Objects larger than this value are discarded. Maps to detection.max_area.

Default: 5000 — must be ≥ 1

export ARCHEO_MAX_AREA=8000

Clustering

ARCHEO_MAX_K · integer

Maximum number of clusters (K) evaluated by the elbow method. Maps to clustering.max_k.

Default: 10 — range: 2–50

export ARCHEO_MAX_K=15

Paths

ARCHEO_DATA_DIR · string

Path to the base directory for input data. Maps to paths.data_dir.

Default: ./data

export ARCHEO_DATA_DIR=/mnt/datasets/archaeological

ARCHEO_RESULTS_DIR · string

Path to the directory where results are written. Maps to paths.results_dir.

Default: ./results

export ARCHEO_RESULTS_DIR=/mnt/output/results

Application

ARCHEO_DEBUG · string

Enable debug mode. Accepts true, 1, or yes (case-insensitive) to enable; any other value leaves debug mode off. Maps to debug.

Default: false

export ARCHEO_DEBUG=true

ARCHEO_LOG_LEVEL · string

Logging verbosity level. The value is uppercased automatically. Maps to log_level.

Default: INFO — accepted values: DEBUG, INFO, WARNING, ERROR

export ARCHEO_LOG_LEVEL=DEBUG

Mapping to config fields

The table below summarizes the full mapping between environment variables and their corresponding YAML config fields.

Environment variable	Config field	Type
ARCHEO_TARGET_COLOR	detection.target_color	string
ARCHEO_MIN_AREA	detection.min_area	integer
ARCHEO_MAX_AREA	detection.max_area	integer
ARCHEO_MAX_K	clustering.max_k	integer
ARCHEO_DATA_DIR	paths.data_dir	path
ARCHEO_RESULTS_DIR	paths.results_dir	path
ARCHEO_DEBUG	debug	boolean
ARCHEO_LOG_LEVEL	log_level	string

Example: CI pipeline

The following shell block shows a typical CI configuration that sets all relevant variables before running the pipeline:

export ARCHEO_TARGET_COLOR="#A98876"
export ARCHEO_MIN_AREA=50
export ARCHEO_MAX_AREA=5000
export ARCHEO_MAX_K=10
export ARCHEO_DATA_DIR=/ci/workspace/images
export ARCHEO_RESULTS_DIR=/ci/workspace/output
export ARCHEO_LOG_LEVEL=INFO
export ARCHEO_DEBUG=false

archeo-cluster pipeline --input-dir "$ARCHEO_DATA_DIR"

Limitations

Not every config field is exposed as an environment variable. The following fields can only be set via config.yaml or the Python API:

• detection.kernel_size
• detection.hue_offset
• detection.saturation_offset
• detection.value_offset
• clustering.random_state
• clustering.min_samples_per_cluster
• clustering.compute_silhouette
• paths.plots_dir

If you need to control these fields in a headless environment, generate a config.yaml programmatically before running the tool, or commit a base config file to your repository.