YamImageProcessor

The YamImageProcessor project provides a modular foundation for building a microscopic image processing desktop application. The system is split into clear layers covering core bootstrapping, processing workflows, UI presentation, and plugin discovery in l ine with the architectural design documents.

Package layout

yam_processor/
├── core/        # Logging, settings, threading, and application bootstrap
├── processing/  # Image processing pipelines (to be implemented)
├── ui/          # Qt-based UI components (to be implemented)
└── plugins/     # Built-in and third-party extensions

The AppCore class coordinates the foundational services:

• Logging – centralised configuration with rotation and optional developer diagnostics.
• Settings – unified QSettings-based manager supporting JSON import/export for reproducible configurations.
• Threading – background task controller built on ThreadPoolExecutor with cooperative cancellation.
• Plugins – discovery of modules in the configured plugin packages that expose a register_module(app_core) function.

Quick start

from yam_processor import AppCore

app_core = AppCore()
app_core.bootstrap()
# Application services (settings, logging, threading, plugins) are now ready.

This repository currently focuses on establishing the foundation; additional processing pipelines and UI components can be buil t on top of the provided scaffolding.

Running the application

First-time setup

1. Create and activate a Python 3.10+ virtual environment (for example, python -m venv .venv and source .venv/bin/activate on macOS/Linux, or .venv\\Scripts\\activate on Windows).
2. Install the runtime dependencies with pip install -r requirements.txt.
3. Optional: install the extended tooling defined in requirements-dev.txt if you plan to run the full quality and testing suite.

Launching the UI

With the environment active, start the main application shell via:

python preprocessing22.py

Alternatively, you can invoke the module launcher directly:

python -m core.application_launcher

On launch a startup dialog prompts you to choose which preprocessing modules should be available and whether diagnostics logging starts enabled. The selections persist across sessions, replacing the previous --diagnostics command-line switch.

On subsequent runs you can reactivate the existing virtual environment and repeat the same command without reinstalling the dependencies. If you prefer to start other entry points that ship with the project, the segmentation and feature extraction pipelines can be launched with:

python segmentation25.py
python extraction18.py

Each script presents the same startup dialog so you can tailor the enabled modules and diagnostics defaults before the main window opens.

Version metadata

The installed build number is exposed via yam_processor.__version__ and yam_processor.get_version(). When package metadata is unavailable—such as running from a source checkout—the helper returns "0.0.0" so tooling still receives a stable string.

Update checks and telemetry

Update polling and telemetry are opt-in features controlled on AppConfiguration. Both remain disabled by default:

from yam_processor import AppConfiguration, AppCore

config = AppConfiguration(
    enable_update_checks=True,
    telemetry_opt_in=True,
)
app_core = AppCore(config)
app_core.bootstrap()

When telemetry is opted in, the flag is persisted through the settings manager under the telemetry/opt_in key. Provide an explicit developer- or user-facing toggle before enabling telemetry so consent is always captured.

Localisation

Strings in the Qt user interface are translation-ready. See docs/TRANSLATIONS.md for instructions on generating and packaging language packs with Qt Linguist tools.

Developer documentation

• docs/DEVELOPER_GUIDE.md – guidance for authoring new processing modules, integrating with AppCore, and meeting logging and UI accessibility conventions.

Development tooling

This repository standardises formatting, linting, and type checking so contributors have a consistent baseline:

• Install the toolchain with pip install -r requirements-dev.txt.
• Format and lint the project via scripts/format.sh, which runs Black, Flake8, and mypy with the configuration defined in pyproject.toml and setup.cfg.

pyproject.toml configures Black (88 character lines, targeting Python 3.10) and applies strict mypy defaults suitable for the codebase. Flake8 mirrors the same line length and enables flake8-bugbear for additional checks to keep the codebase healthy.

Continuous integration

Automated checks run through GitHub Actions on every push and pull request. The workflow provisions Python 3.10, restores a cached .venv, installs runtime dependencies from requirements.txt alongside the tooling in requirements-dev.txt, and runs the same quality gates that contributors use locally:

• black --check ensures formatting stays consistent.
• flake8 enforces style and bug-finding lint rules.
• mypy performs static type analysis.
• pytest (with pytest-qt) exercises the test suite, including the Qt UI components in headless mode.

All jobs must pass before changes are merged. If any command fails locally, resolve the issue before pushing to avoid blocking CI.