# brainglobe/cellfinder architecture

> Architecture diagram of the GitHub repository brainglobe/cellfinder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brainglobe/cellfinder
- Repository: https://github.com/brainglobe/cellfinder

## Overview

##### Project Type Overview
- cellfinder is primarily a scientific/analytical tool with multiple user interfaces:
- A command‐line interface (brainmapper) for automated cell detection and classification.
- A napari plugin for a graphical, interactive experience.
- A Python API for developers to integrate its functionality into custom workflows.
- The overall goal is to manage and process large volumetric images for 3D cell detection, making use of deep learning (e.g., in classification) and classical processing (e.g., detection with filters).

##### Identifying Main Components
- Core Processing Engine: At the heart of the project is the “cellfinder/core” package. This component contains:
- The detection module (cellfinder/core/detect) that includes both plane and volume filters.
- The classification module (cellfinder/core/classify) that contains neural network functionality (e.g., resnet.swift, cube_generator, augmentation).
- Training and configuration components (cellfinder/core/train and cellfinder/core/config).
- Utilities and tools (cellfinder/core/tools), which include IO, image processing, geometry, threading, and system functions.
- Download Component: Managed in “cellfinder/core/download” for fetching or updating data.
- CLI and Main Script: The “cellfinder/core/main.py” and the CLI migration warning assist with command-line usage.
- Napari Plugin: Found under “cellfinder/napari” offering components to integrate with the napari GUI environment (includes detection and train modules for interactive curation).
- Benchmarks and Tests: Dedicated directories (“benchmarks” and “tests”) ensure performance monitoring and functional validation.

- “User Interfaces”
- CLI (command-line interface - brainmapper)
- Napari Plugin (GUI)
- Python API (integrable into external workflows)
- “Core Modules”
- Detection: Show a block labeled “Detect Engine” that further subdivides into “Plane Filters” and “Volume Filters.” Show components like “classical_filter.py”, “tile_walker.py”, and “volume_filter.py.”
- Classification: A block for “Classification Engine,” listing submodules for augmentation, classification, network (e.g., resnet), and cube generation.
- Training Module: Capture “train_yaml.py” and related training configurations.
- Configuration and Tools: A block for “Configuration & Utilities” that includes system, IO, threading, and image processing tools.
- “Download Manager”
- “Testing & Benchmarking”: Optional, but denote “benchmarks” and “tests” directories as external quality/verifications layers that interact with core modules.

- That the configuration tools are used by almost every component.

- For example, from “User Input” in the CLI or napari UI to “Cell Data Processing” (detection and classification) and then output (results display or file IO).
- Calls to external services (if applicable), or integration with other BrainGlobe tools (like brainreg) as indicated in the README.

##### Architectural Patterns and Design Principles
- Layered Architecture: Differentiate presentation (CLI/GUI), application logic (cellfinder/core modules), and data/utility layers (tools, configuration, and IO modules).
- Separation of Concerns: Clearly separate detection, classification, training, and configuration into distinct submodules.
- Modularity: Emphasize modular design (e.g., “cellfinder/core/detect” and “cellfinder/core/classify” components can be independently updated or replaced).
- Extensibility: Note that the napari plugin and Python API interface provide hooks for extension and further integration.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% User Interfaces
    subgraph "User Interfaces"
        CLI["Command-Line Interface (Brainmapper)"]:::ui
        Napari["Napari Plugin"]:::ui
        API["Python API"]:::ui
    end

    %% Core Processing Modules
    subgraph "Core Processing Modules"
        CoreEngine["Core Engine"]:::core
        Detection["Detection Engine"]:::core
        Classify["Classification Engine"]:::core
        Training["Training Module"]:::core
        Config["Configuration"]:::core
        Tools["Utilities & Tools"]:::core
        Download["Download Manager"]:::core
    end

    %% Detection Submodules
    Detection -->|"contains"| Plane["Plane Filters"]:::core
    Detection -->|"contains"| Volume["Volume Filters"]:::core

    %% Quality Assurance
    subgraph "Quality Assurance"
        Bench["Benchmarks"]:::qa
        Tests["Tests"]:::qa
    end

    %% Relationships from User Interfaces to Core Engine
    CLI -->|"invokes"| CoreEngine
    Napari -->|"invokes"| CoreEngine
    API -->|"invokes"| CoreEngine

    %% Core Engine decompositions
    CoreEngine -->|"includes"| Detection
    CoreEngine -->|"includes"| Classify
    CoreEngine -->|"includes"| Training
    CoreEngine -->|"includes"| Config
    CoreEngine -->|"includes"| Tools
    CoreEngine -->|"includes"| Download

    %% Configuration & Tools used by core modules
    Config -->|"usedBy"| Detection
    Config -->|"usedBy"| Classify
    Config -->|"usedBy"| Training
    Tools -->|"usedBy"| Detection
    Tools -->|"usedBy"| Classify
    Tools -->|"usedBy"| Training

    %% Quality Assurance interactions
    Detection ---|"validatedBy"| Bench
    Classify ---|"validatedBy"| Bench
    Training ---|"validatedBy"| Tests
    CoreEngine ---|"monitoredBy"| Tests

    %% Click Events
    click CoreEngine "https://github.com/brainglobe/cellfinder/tree/main/cellfinder/core"
    click Detection "https://github.com/brainglobe/cellfinder/tree/main/cellfinder/core/detect"
    click Plane "https://github.com/brainglobe/cellfinder/tree/main/cellfinder/core/detect/filters/plane"
    click Volume "https://github.com/brainglobe/cellfinder/tree/main/cellfinder/core/detect/filters/volume"
    click Classify "https://github.com/brainglobe/cellfinder/tree/main/cellfinder/core/classify"
    click Training "https://github.com/brainglobe/cellfinder/tree/main/cellfinder/core/train"
    click Config "https://github.com/brainglobe/cellfinder/tree/main/cellfinder/core/config"
    click Tools "https://github.com/brainglobe/cellfinder/tree/main/cellfinder/core/tools"
    click Download "https://github.com/brainglobe/cellfinder/tree/main/cellfinder/core/download"
    click CLI "https://github.com/brainglobe/cellfinder/blob/main/cellfinder/core/main.py"
    click CLI "https://github.com/brainglobe/cellfinder/blob/main/cellfinder/cli_migration_warning.py"
    click Napari "https://github.com/brainglobe/cellfinder/tree/main/cellfinder/napari"
    click Bench "https://github.com/brainglobe/cellfinder/tree/main/benchmarks"
    click Tests "https://github.com/brainglobe/cellfinder/tree/main/tests"

    %% Styles
    classDef ui fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef core fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef qa fill:#fdfd96,stroke:#333,stroke-width:2px;
    
    %% Additional annotation for clarity in data flow
    style API fill:#add8e6,stroke:#333,stroke-width:2px;
    style CoreEngine fill:#98fb98,stroke:#333,stroke-width:2px;
    style Detection fill:#98fb98,stroke:#333,stroke-width:2px;
    style Classify fill:#98fb98,stroke:#333,stroke-width:2px;
    style Training fill:#98fb98,stroke:#333,stroke-width:2px;
    style Config fill:#98fb98,stroke:#333,stroke-width:2px;
    style Tools fill:#98fb98,stroke:#333,stroke-width:2px;
    style Download fill:#98fb98,stroke:#333,stroke-width:2px;
```
