# yangtaowang95/tokencut architecture

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

- Interactive diagram: https://gitdiagram.com/yangtaowang95/tokencut
- Repository: https://github.com/yangtaowang95/tokencut

## Overview

TokenCut is a research application for discovering objects and salient regions from self-supervised vision-transformer features, with a separate weakly supervised detection workflow. The primary path takes an image or dataset through feature extraction, normalized-cut segmentation, and bounding-box or mask output; evaluation and visualization report or render results. The README also documents weakly supervised training and evaluation. Some connections come from the README or SOURCE INDEX rather than complete excerpts, so unsampled implementation details are not expanded into additional flows.

Main entry points: [`unsupervised_saliency_detection/get_saliency.py`](https://github.com/yangtaowang95/tokencut/blob/master/unsupervised_saliency_detection/get_saliency.py) (Saliency Runner), [`main_tokencut.py`](https://github.com/yangtaowang95/tokencut/blob/master/main_tokencut.py) (TokenCut Runner), [`weakly_supvervised_detection/eval.py`](https://github.com/yangtaowang95/tokencut/blob/master/weakly_supvervised_detection/eval.py) (Detection Evaluation), [`weakly_supvervised_detection/main.py`](https://github.com/yangtaowang95/tokencut/blob/master/weakly_supvervised_detection/main.py) (Detection Training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Object Discovery"]
  node_tokencut["TokenCut Runner<br/>[main_tokencut.py]"]
  node_cut["Normalized Cut"]
  node_visuals["Discovery Visualizations<br/>[visualizations.py]"]
end

subgraph group_saliency["Saliency Detection"]
  node_saliency_runner["Saliency Runner<br/>[get_saliency.py]"]
  node_saliency_vit["Saliency Features<br/>[dino.py]"]
  node_saliency_cut["Saliency Cut"]
  node_bilateral["Bilateral Solver"]
  node_saliency_metrics["Saliency Metrics<br/>[metric.py]"]
  node_saliency_output["Saliency Results<br/>[get_saliency.py]"]
end

subgraph group_models["Vision Models"]
  node_model_loader["Model Loader<br/>[networks.py]"]
  node_vit["DINO Vision Transformer"]
end

subgraph group_datasets["Data Inputs"]
  node_dataset["Discovery Datasets<br/>[datasets.py]"]
end

subgraph group_weak["Weak Detection"]
  node_ws_main["Detection Training<br/>[main.py]"]
  node_ws_data["Detection Datasets<br/>[datasets.py]"]
  node_ws_sampler["Training Samplers<br/>[samplers.py]"]
  node_ws_vit["Detection Transformer"]
  node_finetune["Linear Fine-tuning<br/>[finetune.py]"]
  node_ws_eval["Detection Evaluation<br/>[eval.py]"]
  node_ws_metrics["Detection Metrics<br/>[metrics.py]"]
  node_ws_meters["Evaluation Meters<br/>[meters.py]"]
  node_ws_visuals["Detection Visualizations<br/>[visualization.py]"]
end

node_user(("Researcher"))
node_image["Input Images"]

node_user -->|"runs discovery"| node_tokencut
node_image -->|"supplies image"| node_tokencut
node_tokencut -->|"loads dataset"| node_dataset
node_tokencut -->|"loads model"| node_model_loader
node_model_loader -->|"constructs transformer"| node_vit
node_tokencut -->|"computes cut"| node_cut
node_tokencut -->|"renders results"| node_visuals
node_user -->|"runs saliency"| node_saliency_runner
node_image -->|"supplies image"| node_saliency_runner
node_saliency_runner -->|"extracts features"| node_saliency_vit
node_saliency_runner -->|"computes cut"| node_saliency_cut
node_saliency_runner -->|"refines mask"| node_bilateral
node_saliency_runner -->|"evaluates mask"| node_saliency_metrics
node_saliency_runner -->|"writes results"| node_saliency_output
node_user -->|"trains detector"| node_ws_main
node_ws_main -->|"builds datasets"| node_ws_data
node_ws_main -->|"selects samples"| node_ws_sampler
node_ws_main -->|"uses transformer"| node_ws_vit
node_user -->|"runs fine-tuning"| node_finetune
node_user -->|"runs evaluation"| node_ws_eval
node_ws_eval -->|"loads dataset"| node_ws_data
node_ws_eval -->|"computes metrics"| node_ws_metrics
node_ws_eval -->|"tracks results"| node_ws_meters
node_ws_eval -->|"renders detections"| node_ws_visuals

click node_dataset "https://github.com/yangtaowang95/tokencut/blob/master/datasets.py"
click node_tokencut "https://github.com/yangtaowang95/tokencut/blob/master/main_tokencut.py"
click node_model_loader "https://github.com/yangtaowang95/tokencut/blob/master/networks.py"
click node_vit "https://github.com/yangtaowang95/tokencut/blob/master/dino/vision_transformer.py"
click node_cut "https://github.com/yangtaowang95/tokencut/blob/master/object_discovery.py"
click node_visuals "https://github.com/yangtaowang95/tokencut/blob/master/visualizations.py"
click node_saliency_runner "https://github.com/yangtaowang95/tokencut/blob/master/unsupervised_saliency_detection/get_saliency.py"
click node_saliency_vit "https://github.com/yangtaowang95/tokencut/blob/master/unsupervised_saliency_detection/dino.py"
click node_saliency_cut "https://github.com/yangtaowang95/tokencut/blob/master/unsupervised_saliency_detection/object_discovery.py"
click node_bilateral "https://github.com/yangtaowang95/tokencut/blob/master/unsupervised_saliency_detection/bilateral_solver.py"
click node_saliency_metrics "https://github.com/yangtaowang95/tokencut/blob/master/unsupervised_saliency_detection/metric.py"
click node_saliency_output "https://github.com/yangtaowang95/tokencut/blob/master/unsupervised_saliency_detection/get_saliency.py"
click node_ws_main "https://github.com/yangtaowang95/tokencut/blob/master/weakly_supvervised_detection/main.py"
click node_ws_data "https://github.com/yangtaowang95/tokencut/blob/master/weakly_supvervised_detection/datasets.py"
click node_ws_sampler "https://github.com/yangtaowang95/tokencut/blob/master/weakly_supvervised_detection/samplers.py"
click node_ws_vit "https://github.com/yangtaowang95/tokencut/blob/master/weakly_supvervised_detection/vision_transformer.py"
click node_finetune "https://github.com/yangtaowang95/tokencut/blob/master/weakly_supvervised_detection/finetune.py"
click node_ws_eval "https://github.com/yangtaowang95/tokencut/blob/master/weakly_supvervised_detection/eval.py"
click node_ws_metrics "https://github.com/yangtaowang95/tokencut/blob/master/weakly_supvervised_detection/metrics.py"
click node_ws_meters "https://github.com/yangtaowang95/tokencut/blob/master/weakly_supvervised_detection/meters.py"
click node_ws_visuals "https://github.com/yangtaowang95/tokencut/blob/master/weakly_supvervised_detection/visualization.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_tokencut,node_cut,node_visuals toneBlue
class node_saliency_runner,node_saliency_vit,node_saliency_cut,node_bilateral,node_saliency_metrics,node_saliency_output toneAmber
class node_model_loader,node_vit toneMint
class node_dataset toneRose
class node_ws_main,node_ws_data,node_ws_sampler,node_ws_vit,node_finetune,node_ws_eval,node_ws_metrics,node_ws_meters,node_ws_visuals,node_user,node_image toneIndigo
```

## Components

### Object Discovery

- [TokenCut Runner](https://github.com/yangtaowang95/tokencut/blob/master/main_tokencut.py): `main_tokencut.py`
- [Normalized Cut](https://github.com/yangtaowang95/tokencut/blob/master/object_discovery.py): `object_discovery.py`
- [Discovery Visualizations](https://github.com/yangtaowang95/tokencut/blob/master/visualizations.py): `visualizations.py`

### Saliency Detection

- [Saliency Runner](https://github.com/yangtaowang95/tokencut/blob/master/unsupervised_saliency_detection/get_saliency.py): `unsupervised_saliency_detection/get_saliency.py`
- [Saliency Features](https://github.com/yangtaowang95/tokencut/blob/master/unsupervised_saliency_detection/dino.py): `unsupervised_saliency_detection/dino.py`
- [Saliency Cut](https://github.com/yangtaowang95/tokencut/blob/master/unsupervised_saliency_detection/object_discovery.py): `unsupervised_saliency_detection/object_discovery.py`
- [Bilateral Solver](https://github.com/yangtaowang95/tokencut/blob/master/unsupervised_saliency_detection/bilateral_solver.py): `unsupervised_saliency_detection/bilateral_solver.py`
- [Saliency Metrics](https://github.com/yangtaowang95/tokencut/blob/master/unsupervised_saliency_detection/metric.py): `unsupervised_saliency_detection/metric.py`
- [Saliency Results](https://github.com/yangtaowang95/tokencut/blob/master/unsupervised_saliency_detection/get_saliency.py): `unsupervised_saliency_detection/get_saliency.py`

### Vision Models

- [Model Loader](https://github.com/yangtaowang95/tokencut/blob/master/networks.py): `networks.py`
- [DINO Vision Transformer](https://github.com/yangtaowang95/tokencut/blob/master/dino/vision_transformer.py): `dino/vision_transformer.py`

### Data Inputs

- [Discovery Datasets](https://github.com/yangtaowang95/tokencut/blob/master/datasets.py): `datasets.py`

### Weak Detection

- [Detection Training](https://github.com/yangtaowang95/tokencut/blob/master/weakly_supvervised_detection/main.py): `weakly_supvervised_detection/main.py`
- [Detection Datasets](https://github.com/yangtaowang95/tokencut/blob/master/weakly_supvervised_detection/datasets.py): `weakly_supvervised_detection/datasets.py`
- [Training Samplers](https://github.com/yangtaowang95/tokencut/blob/master/weakly_supvervised_detection/samplers.py): `weakly_supvervised_detection/samplers.py`
- [Detection Transformer](https://github.com/yangtaowang95/tokencut/blob/master/weakly_supvervised_detection/vision_transformer.py): `weakly_supvervised_detection/vision_transformer.py`
- [Linear Fine-tuning](https://github.com/yangtaowang95/tokencut/blob/master/weakly_supvervised_detection/finetune.py): `weakly_supvervised_detection/finetune.py`
- [Detection Evaluation](https://github.com/yangtaowang95/tokencut/blob/master/weakly_supvervised_detection/eval.py): `weakly_supvervised_detection/eval.py`
- [Detection Metrics](https://github.com/yangtaowang95/tokencut/blob/master/weakly_supvervised_detection/metrics.py): `weakly_supvervised_detection/metrics.py`
- [Evaluation Meters](https://github.com/yangtaowang95/tokencut/blob/master/weakly_supvervised_detection/meters.py): `weakly_supvervised_detection/meters.py`
- [Detection Visualizations](https://github.com/yangtaowang95/tokencut/blob/master/weakly_supvervised_detection/visualization.py): `weakly_supvervised_detection/visualization.py`

### Other components

- **Researcher**
- **Input Images**

## Connections

- Researcher → TokenCut Runner: runs discovery (evidence: `README.md`)
- Input Images → TokenCut Runner: supplies image (evidence: `README.md`)
- TokenCut Runner → Discovery Datasets: loads dataset (evidence: `main_tokencut.py`)
- TokenCut Runner → Model Loader: loads model (evidence: `main_tokencut.py`)
- Model Loader → DINO Vision Transformer: constructs transformer (evidence: `networks.py`)
- TokenCut Runner → Normalized Cut: computes cut (evidence: `main_tokencut.py`)
- TokenCut Runner → Discovery Visualizations: renders results (evidence: `main_tokencut.py`)
- Researcher → Saliency Runner: runs saliency (evidence: `README.md`)
- Input Images → Saliency Runner: supplies image (evidence: `README.md`)
- Saliency Runner → Saliency Features: extracts features (evidence: `unsupervised_saliency_detection/get_saliency.py`)
- Saliency Runner → Saliency Cut: computes cut (evidence: `unsupervised_saliency_detection/get_saliency.py`)
- Saliency Runner → Bilateral Solver: refines mask (evidence: `unsupervised_saliency_detection/get_saliency.py`)
- Saliency Runner → Saliency Metrics: evaluates mask (evidence: `unsupervised_saliency_detection/get_saliency.py`)
- Saliency Runner → Saliency Results: writes results (evidence: `unsupervised_saliency_detection/get_saliency.py`)
- Researcher → Detection Training: trains detector (evidence: `README.md`)
- Detection Training → Detection Datasets: builds datasets (evidence: `weakly_supvervised_detection/main.py`)
- Detection Training → Training Samplers: selects samples (evidence: `weakly_supvervised_detection/main.py`)
- Detection Training → Detection Transformer: uses transformer (evidence: `weakly_supvervised_detection/main.py`)
- Researcher → Linear Fine-tuning: runs fine-tuning (evidence: `README.md`)
- Researcher → Detection Evaluation: runs evaluation (evidence: `README.md`)
- Detection Evaluation → Detection Datasets: loads dataset (evidence: `weakly_supvervised_detection/eval.py`)
- Detection Evaluation → Detection Metrics: computes metrics (evidence: `weakly_supvervised_detection/eval.py`)
- Detection Evaluation → Evaluation Meters: tracks results (evidence: `weakly_supvervised_detection/eval.py`)
- Detection Evaluation → Detection Visualizations: renders detections (evidence: `weakly_supvervised_detection/eval.py`)
