# paulden/guitar-fingering-recognition architecture

> Architecture diagram of the GitHub repository paulden/guitar-fingering-recognition, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/paulden/guitar-fingering-recognition
- Repository: https://github.com/paulden/guitar-fingering-recognition

## Overview

This is an experimental OpenCV project for recognizing guitar fingering from photographs. Its main demonstrated workflow loads an image, rotates and crops it to the guitar neck, then detects strings and frets; a separate, currently failing branch attempts hand and fingertip detection. The README presents the test-named scripts as the way to run and view these experiments, so they are shown as user-facing runners. Watershed segmentation is an explicitly unused experiment. Relationships are limited to calls visible in excerpts or capabilities documented in the README.

Main entry points: [`rotate_crop.py`](https://github.com/paulden/guitar-fingering-recognition/blob/master/rotate_crop.py) (Neck rotate/crop), [`image.py`](https://github.com/paulden/guitar-fingering-recognition/blob/master/image.py) (Image operations), [`grid_detection.py`](https://github.com/paulden/guitar-fingering-recognition/blob/master/grid_detection.py) (String/fret detection), [`rotate_crop_tests.py`](https://github.com/paulden/guitar-fingering-recognition/blob/master/rotate_crop_tests.py) (Rotate/crop runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_preprocess["Image preparation"]
  node_crop_runner["Rotate/crop runner"]
  node_rotate_crop["Neck rotate/crop<br/>[rotate_crop.py]"]
end

subgraph group_detect["Neck detection"]
  node_grid_runner["Grid runner"]
  node_grid["String/fret detection<br/>[grid_detection.py]"]
  node_strings["String-line data<br/>[strings.py]"]
  node_finger_runner["Hand-detection runner"]
  node_finger["Hand/fingertip detection"]
  node_watershed["Watershed experiment<br/>[watershed.py]"]
end

subgraph group_support["Shared image tools"]
  node_image["Image operations<br/>[image.py]"]
  node_functions["Image helpers<br/>[functions.py]"]
end

node_user(("User"))
node_photos["Guitar photos"]

node_user -->|"runs"| node_crop_runner
node_user -->|"runs"| node_grid_runner
node_user -->|"runs"| node_finger_runner
node_photos -->|"loads images"| node_crop_runner
node_photos -->|"loads images"| node_grid_runner
node_photos -->|"loads images"| node_finger_runner
node_crop_runner -->|"creates images"| node_image
node_crop_runner -->|"calls"| node_rotate_crop
node_rotate_crop -->|"uses"| node_image
node_rotate_crop -->|"uses helpers"| node_functions
node_grid_runner -->|"calls"| node_rotate_crop
node_grid_runner -->|"calls"| node_grid
node_grid -->|"uses"| node_image
node_grid -->|"creates"| node_strings
node_grid -->|"uses helpers"| node_functions
node_finger_runner -->|"calls"| node_rotate_crop
node_finger_runner -->|"calls"| node_finger
node_finger -->|"uses"| node_image
node_watershed -->|"uses"| node_rotate_crop
node_watershed -->|"uses"| node_image

click node_photos "https://github.com/paulden/guitar-fingering-recognition/tree/master/pictures"
click node_crop_runner "https://github.com/paulden/guitar-fingering-recognition/blob/master/rotate_crop_tests.py"
click node_image "https://github.com/paulden/guitar-fingering-recognition/blob/master/image.py"
click node_rotate_crop "https://github.com/paulden/guitar-fingering-recognition/blob/master/rotate_crop.py"
click node_functions "https://github.com/paulden/guitar-fingering-recognition/blob/master/functions.py"
click node_grid_runner "https://github.com/paulden/guitar-fingering-recognition/blob/master/grid_detection_tests.py"
click node_grid "https://github.com/paulden/guitar-fingering-recognition/blob/master/grid_detection.py"
click node_strings "https://github.com/paulden/guitar-fingering-recognition/blob/master/strings.py"
click node_finger_runner "https://github.com/paulden/guitar-fingering-recognition/blob/master/finger_detection_tests.py"
click node_finger "https://github.com/paulden/guitar-fingering-recognition/blob/master/finger_detection.py"
click node_watershed "https://github.com/paulden/guitar-fingering-recognition/blob/master/watershed.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_crop_runner,node_rotate_crop,node_user toneBlue
class node_grid_runner,node_grid,node_strings,node_finger_runner,node_finger,node_watershed toneAmber
class node_image,node_functions toneMint
class node_photos toneTeal
```

## Components

### Image preparation

- [Rotate/crop runner](https://github.com/paulden/guitar-fingering-recognition/blob/master/rotate_crop_tests.py): `rotate_crop_tests.py`
- [Neck rotate/crop](https://github.com/paulden/guitar-fingering-recognition/blob/master/rotate_crop.py): `rotate_crop.py`

### Neck detection

- [Grid runner](https://github.com/paulden/guitar-fingering-recognition/blob/master/grid_detection_tests.py): `grid_detection_tests.py`
- [String/fret detection](https://github.com/paulden/guitar-fingering-recognition/blob/master/grid_detection.py): `grid_detection.py`
- [String-line data](https://github.com/paulden/guitar-fingering-recognition/blob/master/strings.py): `strings.py`
- [Hand-detection runner](https://github.com/paulden/guitar-fingering-recognition/blob/master/finger_detection_tests.py): `finger_detection_tests.py`
- [Hand/fingertip detection](https://github.com/paulden/guitar-fingering-recognition/blob/master/finger_detection.py): `finger_detection.py`
- [Watershed experiment](https://github.com/paulden/guitar-fingering-recognition/blob/master/watershed.py): `watershed.py`

### Shared image tools

- [Image operations](https://github.com/paulden/guitar-fingering-recognition/blob/master/image.py): `image.py`
- [Image helpers](https://github.com/paulden/guitar-fingering-recognition/blob/master/functions.py): `functions.py`

### Other components

- **User**
- [Guitar photos](https://github.com/paulden/guitar-fingering-recognition/tree/master/pictures): `pictures`

## Connections

- User → Rotate/crop runner: runs (evidence: `README.md`)
- User → Grid runner: runs (evidence: `README.md`)
- User → Hand-detection runner: runs (evidence: `README.md`)
- Guitar photos → Rotate/crop runner: loads images (evidence: `rotate_crop_tests.py`)
- Guitar photos → Grid runner: loads images (evidence: `grid_detection_tests.py`)
- Guitar photos → Hand-detection runner: loads images (evidence: `finger_detection_tests.py`)
- Rotate/crop runner → Image operations: creates images (evidence: `rotate_crop_tests.py`)
- Rotate/crop runner → Neck rotate/crop: calls (evidence: `rotate_crop_tests.py`)
- Neck rotate/crop → Image operations: uses (evidence: `rotate_crop.py`)
- Neck rotate/crop → Image helpers: uses helpers (evidence: `rotate_crop.py`)
- Grid runner → Neck rotate/crop: calls (evidence: `grid_detection_tests.py`)
- Grid runner → String/fret detection: calls (evidence: `grid_detection_tests.py`)
- String/fret detection → Image operations: uses (evidence: `grid_detection.py`)
- String/fret detection → String-line data: creates (evidence: `grid_detection.py`)
- String/fret detection → Image helpers: uses helpers (evidence: `grid_detection.py`)
- Hand-detection runner → Neck rotate/crop: calls (evidence: `finger_detection_tests.py`)
- Hand-detection runner → Hand/fingertip detection: calls (evidence: `finger_detection_tests.py`)
- Hand/fingertip detection → Image operations: uses (evidence: `finger_detection.py`)
- Watershed experiment → Neck rotate/crop: uses (evidence: `watershed.py`)
- Watershed experiment → Image operations: uses (evidence: `watershed.py`)
