# bbvisual/countex architecture

> Architecture diagram of the GitHub repository bbvisual/countex, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bbvisual/countex
- Repository: https://github.com/bbvisual/countex

## Overview

CountEx is a fine-grained visual counting system: users specify a target and a distractor, optionally with visual exemplars, and the model predicts the target count while suppressing the distractor. Its main workflow is data preparation, model inference and training, then evaluation. The repository also contains a separate count-only-supervision extension, with density-only and detection-prior/alternating-training variants. Edges reflect the README and shown source references; unsampled subsystem details and links are omitted where their wiring is not evidenced.

Main entry points: [`src/hf_model/CountEX.py`](https://github.com/bbvisual/countex/blob/main/src/hf_model/CountEX.py) (CountEx Model), [`src/train.py`](https://github.com/bbvisual/countex/blob/main/src/train.py) (Training Entry), [`src/utils.py`](https://github.com/bbvisual/countex/blob/main/src/utils.py) (Data Preparation), [`count_only/src/hf_model/CountEXStage2.py`](https://github.com/bbvisual/countex/blob/main/count_only/src/hf_model/CountEXStage2.py) (Detection-Prior Model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_main["CountEx Core"]
  node_data_prep["Data Preparation<br/>[utils.py]"]
  node_core_model["CountEx Model<br/>[CountEX.py]"]
  node_criterion["Matching Losses<br/>[criterion.py]"]
  node_trainer["Fine-Grained Trainer<br/>[trainer.py]"]
  node_train["Training Entry<br/>[train.py]"]
end

subgraph group_countonly["Count-Only Extension"]
  node_count_data["Count-Only Data Tools"]
  node_count_models["Count-Only Model Variants"]
  node_density_model["Density-Only Model"]
  node_stage2_model["Detection-Prior Model<br/>[CountEXStage2.py]"]
  node_alternating_trainer["Alternating Trainer"]
  node_count_train["Count-Only Training<br/>[train.py]"]
  node_alternating_train["Alternating Training Entry"]
end

subgraph group_shared["Modeling Infrastructure"]
  node_grounding["Grounding DINO"]
end

subgraph group_evaluation["Evaluation"]
  node_eval["Core Evaluation<br/>[eval.py]"]
  node_count_eval["Count-Only Evaluation<br/>[eval.py]"]
  node_density_eval["Density Evaluation<br/>[eval_density.py]"]
  node_localization_eval["Localization Evaluation"]
  node_matched_eval["Matched Evaluations<br/>[eval_matched.py]"]
end

node_researcher(("Researcher"))
node_cocount[("CoCount Dataset")]
node_pairtally[("PairTally Benchmark")]

node_researcher -->|"selects data"| node_cocount
node_cocount -->|"trains on"| node_train
node_researcher -->|"specifies query"| node_core_model
node_data_prep -->|"prepares batches"| node_trainer
node_train -->|"loads model"| node_core_model
node_train -->|"configures loss"| node_criterion
node_train -->|"creates trainer"| node_trainer
node_train -->|"uses utilities"| node_data_prep
node_core_model -->|"extends backbone"| node_grounding
node_trainer -->|"uses utilities"| node_data_prep
node_eval -->|"evaluates model"| node_core_model
node_eval -->|"uses utilities"| node_data_prep
node_researcher -->|"selects benchmark"| node_pairtally
node_pairtally -.->|"evaluates transfer"| node_eval
node_researcher -->|"prepares supervision"| node_count_data
node_count_train -->|"selects variants"| node_count_models
node_count_train -->|"uses trainer"| node_trainer
node_count_train -->|"uses losses"| node_criterion
node_count_models -->|"uses backbone"| node_grounding
node_density_model -->|"uses backbone"| node_grounding
node_stage2_model -->|"extends model"| node_core_model
node_alternating_train -->|"loads variant"| node_stage2_model
node_alternating_train -->|"creates trainer"| node_alternating_trainer
node_alternating_trainer -->|"uses utilities"| node_data_prep
node_count_eval -->|"evaluates model"| node_core_model
node_density_eval -->|"evaluates model"| node_density_model
node_density_eval -->|"evaluates variant"| node_stage2_model
node_localization_eval -->|"evaluates variant"| node_stage2_model
node_matched_eval -->|"evaluates variant"| node_stage2_model

click node_data_prep "https://github.com/bbvisual/countex/blob/main/src/utils.py"
click node_core_model "https://github.com/bbvisual/countex/blob/main/src/hf_model/CountEX.py"
click node_grounding "https://github.com/bbvisual/countex/blob/main/src/hf_model/modeling_grounding_dino.py"
click node_criterion "https://github.com/bbvisual/countex/blob/main/src/criterion.py"
click node_trainer "https://github.com/bbvisual/countex/blob/main/src/trainer.py"
click node_train "https://github.com/bbvisual/countex/blob/main/src/train.py"
click node_eval "https://github.com/bbvisual/countex/blob/main/src/eval.py"
click node_count_data "https://github.com/bbvisual/countex/tree/main/count_only/src"
click node_count_models "https://github.com/bbvisual/countex/tree/main/count_only/src/hf_model"
click node_density_model "https://github.com/bbvisual/countex/blob/main/count_only/src/hf_model/CountEXDensityOnly.py"
click node_stage2_model "https://github.com/bbvisual/countex/blob/main/count_only/src/hf_model/CountEXStage2.py"
click node_alternating_trainer "https://github.com/bbvisual/countex/blob/main/count_only/src/alternating_trainer.py"
click node_count_train "https://github.com/bbvisual/countex/blob/main/count_only/src/train.py"
click node_alternating_train "https://github.com/bbvisual/countex/blob/main/count_only/src/train_alternating.py"
click node_count_eval "https://github.com/bbvisual/countex/blob/main/count_only/src/eval.py"
click node_density_eval "https://github.com/bbvisual/countex/blob/main/count_only/src/eval_density.py"
click node_localization_eval "https://github.com/bbvisual/countex/blob/main/count_only/src/eval_localization.py"
click node_matched_eval "https://github.com/bbvisual/countex/blob/main/count_only/src/eval_matched.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_data_prep,node_core_model,node_criterion,node_trainer,node_train toneBlue
class node_count_data,node_count_models,node_density_model,node_stage2_model,node_alternating_trainer,node_count_train,node_alternating_train,node_cocount,node_pairtally toneAmber
class node_grounding toneMint
class node_eval,node_count_eval,node_density_eval,node_localization_eval,node_matched_eval toneRose
class node_researcher toneIndigo
```

## Components

### CountEx Core

- [Data Preparation](https://github.com/bbvisual/countex/blob/main/src/utils.py): `src/utils.py`
- [CountEx Model](https://github.com/bbvisual/countex/blob/main/src/hf_model/CountEX.py): `src/hf_model/CountEX.py`
- [Matching Losses](https://github.com/bbvisual/countex/blob/main/src/criterion.py): `src/criterion.py`
- [Fine-Grained Trainer](https://github.com/bbvisual/countex/blob/main/src/trainer.py): `src/trainer.py`
- [Training Entry](https://github.com/bbvisual/countex/blob/main/src/train.py): `src/train.py`

### Count-Only Extension

- [Count-Only Data Tools](https://github.com/bbvisual/countex/tree/main/count_only/src): `count_only/src`
- [Count-Only Model Variants](https://github.com/bbvisual/countex/tree/main/count_only/src/hf_model): `count_only/src/hf_model`
- [Density-Only Model](https://github.com/bbvisual/countex/blob/main/count_only/src/hf_model/CountEXDensityOnly.py): `count_only/src/hf_model/CountEXDensityOnly.py`
- [Detection-Prior Model](https://github.com/bbvisual/countex/blob/main/count_only/src/hf_model/CountEXStage2.py): `count_only/src/hf_model/CountEXStage2.py`
- [Alternating Trainer](https://github.com/bbvisual/countex/blob/main/count_only/src/alternating_trainer.py): `count_only/src/alternating_trainer.py`
- [Count-Only Training](https://github.com/bbvisual/countex/blob/main/count_only/src/train.py): `count_only/src/train.py`
- [Alternating Training Entry](https://github.com/bbvisual/countex/blob/main/count_only/src/train_alternating.py): `count_only/src/train_alternating.py`

### Modeling Infrastructure

- [Grounding DINO](https://github.com/bbvisual/countex/blob/main/src/hf_model/modeling_grounding_dino.py): `src/hf_model/modeling_grounding_dino.py`

### Evaluation

- [Core Evaluation](https://github.com/bbvisual/countex/blob/main/src/eval.py): `src/eval.py`
- [Count-Only Evaluation](https://github.com/bbvisual/countex/blob/main/count_only/src/eval.py): `count_only/src/eval.py`
- [Density Evaluation](https://github.com/bbvisual/countex/blob/main/count_only/src/eval_density.py): `count_only/src/eval_density.py`
- [Localization Evaluation](https://github.com/bbvisual/countex/blob/main/count_only/src/eval_localization.py): `count_only/src/eval_localization.py`
- [Matched Evaluations](https://github.com/bbvisual/countex/blob/main/count_only/src/eval_matched.py): `count_only/src/eval_matched.py`

### Other components

- **Researcher**
- **CoCount Dataset**
- **PairTally Benchmark**

## Connections

- Researcher → CoCount Dataset: selects data (evidence: `README.md`)
- CoCount Dataset → Training Entry: trains on (evidence: `README.md`)
- Researcher → CountEx Model: specifies query (evidence: `README.md`)
- Data Preparation → Fine-Grained Trainer: prepares batches (evidence: `src/trainer.py`)
- Training Entry → CountEx Model: loads model (evidence: `src/train.py`)
- Training Entry → Matching Losses: configures loss (evidence: `src/train.py`)
- Training Entry → Fine-Grained Trainer: creates trainer (evidence: `src/train.py`)
- Training Entry → Data Preparation: uses utilities (evidence: `src/train.py`)
- CountEx Model → Grounding DINO: extends backbone (evidence: `src/hf_model/CountEX.py`)
- Fine-Grained Trainer → Data Preparation: uses utilities (evidence: `src/trainer.py`)
- Core Evaluation → CountEx Model: evaluates model (evidence: `src/eval.py`)
- Core Evaluation → Data Preparation: uses utilities (evidence: `src/eval.py`)
- Researcher → PairTally Benchmark: selects benchmark (evidence: `README.md`)
- PairTally Benchmark → Core Evaluation: evaluates transfer (evidence: `README.md`)
- Researcher → Count-Only Data Tools: prepares supervision (evidence: `count_only/src/build_acc_only_dataset.py`)
- Count-Only Training → Count-Only Model Variants: selects variants (evidence: `count_only/src/train.py`)
- Count-Only Training → Fine-Grained Trainer: uses trainer (evidence: `count_only/src/train.py`)
- Count-Only Training → Matching Losses: uses losses (evidence: `count_only/src/train.py`)
- Count-Only Model Variants → Grounding DINO: uses backbone (evidence: `count_only/src/hf_model/CountEX.py`)
- Density-Only Model → Grounding DINO: uses backbone (evidence: `count_only/src/hf_model/CountEXDensityOnly.py`)
- Detection-Prior Model → CountEx Model: extends model (evidence: `count_only/src/hf_model/CountEXStage2.py`)
- Alternating Training Entry → Detection-Prior Model: loads variant (evidence: `count_only/src/train_alternating.py`)
- Alternating Training Entry → Alternating Trainer: creates trainer (evidence: `count_only/src/train_alternating.py`)
- Alternating Trainer → Data Preparation: uses utilities (evidence: `count_only/src/alternating_trainer.py`)
- Count-Only Evaluation → CountEx Model: evaluates model (evidence: `count_only/src/eval.py`)
- Density Evaluation → Density-Only Model: evaluates model (evidence: `count_only/src/eval_density.py`)
- Density Evaluation → Detection-Prior Model: evaluates variant (evidence: `count_only/src/eval_density.py`)
- Localization Evaluation → Detection-Prior Model: evaluates variant (evidence: `count_only/src/eval_localization.py`)
- Matched Evaluations → Detection-Prior Model: evaluates variant (evidence: `count_only/src/eval_matched.py`)