# makarandtapaswi/video_shotthread_scenedetect architecture

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

- Interactive diagram: https://gitdiagram.com/makarandtapaswi/video_shotthread_scenedetect
- Repository: https://github.com/makarandtapaswi/video_shotthread_scenedetect

## Overview

This MATLAB video-analysis toolkit turns an initialized episode into shot-similarity scores, shot threads, and scene-break locations, with HTML visualizations for the latter results. Its documented workflow assumes shot detection and frame reading already exist; episode-specific setup is provided through initializers. The graph preserves the separate threading and dynamic-programming scene-detection branches. The README establishes the example call sequence, but most implementation files were not sampled, so internal calls and the visualization handoff are not inferred where they are undocumented.

Main entry points: [`threading/shot_similarity.m`](https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/threading/shot_similarity.m) (Shot similarity), [`threading/similarity_to_threads.m`](https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/threading/similarity_to_threads.m) (Thread assignment), [`visualization/visualize_threads_via_htmlrender.m`](https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/visualization/visualize_threads_via_htmlrender.m) (Thread visualization), [`visualization/visualize_scenes_via_htmlrender.m`](https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/visualization/visualize_scenes_via_htmlrender.m) (Scene visualization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Episode setup"]
  node_video_init["Episode setup<br/>[BBT.m]"]
  node_params["Analysis parameters<br/>[initParams.m]"]
  node_frame_source["Frame access"]
  node_shot_events["Shot events"]
end

subgraph group_analysis["Video analysis"]
  node_shot_similarity["Shot similarity<br/>[shot_similarity.m]"]
  node_image_similarity["Image comparison"]
  node_histogram_mex["ND histogram MEX<br/>[imhist_nd_fast.cpp]"]
  node_scene_detection["Scene detection<br/>[dp_scenes.m]"]
end

subgraph group_threading["Shot threading"]
  node_shot_threads["Thread assignment"]
  node_cliques["Maximal cliques<br/>[maximalCliques.m]"]
end

subgraph group_visualization["Result visualization"]
  node_thread_visualizer["Thread visualization"]
  node_scene_visualizer["Scene visualization"]
  node_html_renderer["HTML renderer<br/>[gen_html.py]"]
  node_thread_template["Thread template<br/>[threading.html]"]
  node_scene_template["Scene template<br/>[scenes.html]"]
end

node_user(("Analyst"))

node_user -->|"initializes video"| node_video_init
node_user -->|"initializes parameters"| node_params
node_user -->|"computes similarity"| node_shot_similarity
node_user -->|"converts similarity"| node_shot_threads
node_user -->|"computes scenes"| node_scene_detection
node_user -->|"provides frame access"| node_frame_source
node_shot_similarity -->|"returns scores for"| node_shot_threads
node_shot_threads -->|"visualizes threads"| node_thread_visualizer
node_scene_detection -->|"visualizes scene breaks"| node_scene_visualizer
node_shot_events -.->|"episode shot data"| node_video_init
node_shot_similarity -.->|"uses image comparison"| node_image_similarity
node_shot_similarity -.->|"reads frames"| node_frame_source
node_shot_threads -.->|"finds cliques"| node_cliques
node_thread_visualizer -.->|"renders through"| node_html_renderer
node_scene_visualizer -.->|"renders through"| node_html_renderer
node_thread_visualizer -.->|"uses template"| node_thread_template
node_scene_visualizer -.->|"uses template"| node_scene_template

click node_video_init "https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/initializers/BBT.m"
click node_params "https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/initializers/initParams.m"
click node_shot_events "https://github.com/makarandtapaswi/video_shotthread_scenedetect/tree/master/data/shot_boundaries"
click node_shot_similarity "https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/threading/shot_similarity.m"
click node_image_similarity "https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/threading/are_images_similar.m"
click node_histogram_mex "https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/ext/imhist_nd_fast/imhist_nd_fast.cpp"
click node_shot_threads "https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/threading/similarity_to_threads.m"
click node_cliques "https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/utilities/maximalCliques.m"
click node_scene_detection "https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/scenes/dp_scenes.m"
click node_thread_visualizer "https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/visualization/visualize_threads_via_htmlrender.m"
click node_scene_visualizer "https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/visualization/visualize_scenes_via_htmlrender.m"
click node_html_renderer "https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/visualization/gen_html.py"
click node_thread_template "https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/visualization/render_templates/threading.html"
click node_scene_template "https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/visualization/render_templates/scenes.html"

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_video_init,node_params,node_frame_source,node_shot_events toneBlue
class node_shot_similarity,node_image_similarity,node_histogram_mex,node_scene_detection toneAmber
class node_shot_threads,node_cliques toneMint
class node_thread_visualizer,node_scene_visualizer,node_html_renderer,node_thread_template,node_scene_template toneRose
class node_user toneIndigo
```

## Components

### Episode setup

- [Episode setup](https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/initializers/BBT.m): `initializers/BBT.m`
- [Analysis parameters](https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/initializers/initParams.m): `initializers/initParams.m`
- **Frame access**
- [Shot events](https://github.com/makarandtapaswi/video_shotthread_scenedetect/tree/master/data/shot_boundaries): `data/shot_boundaries`

### Video analysis

- [Shot similarity](https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/threading/shot_similarity.m): `threading/shot_similarity.m`
- [Image comparison](https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/threading/are_images_similar.m): `threading/are_images_similar.m`
- [ND histogram MEX](https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/ext/imhist_nd_fast/imhist_nd_fast.cpp): `ext/imhist_nd_fast/imhist_nd_fast.cpp`
- [Scene detection](https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/scenes/dp_scenes.m): `scenes/dp_scenes.m`

### Shot threading

- [Thread assignment](https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/threading/similarity_to_threads.m): `threading/similarity_to_threads.m`
- [Maximal cliques](https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/utilities/maximalCliques.m): `utilities/maximalCliques.m`

### Result visualization

- [Thread visualization](https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/visualization/visualize_threads_via_htmlrender.m): `visualization/visualize_threads_via_htmlrender.m`
- [Scene visualization](https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/visualization/visualize_scenes_via_htmlrender.m): `visualization/visualize_scenes_via_htmlrender.m`
- [HTML renderer](https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/visualization/gen_html.py): `visualization/gen_html.py`
- [Thread template](https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/visualization/render_templates/threading.html): `visualization/render_templates/threading.html`
- [Scene template](https://github.com/makarandtapaswi/video_shotthread_scenedetect/blob/master/visualization/render_templates/scenes.html): `visualization/render_templates/scenes.html`

### Other components

- **Analyst**

## Connections

- Analyst → Episode setup: initializes video (evidence: `README.md`)
- Analyst → Analysis parameters: initializes parameters (evidence: `README.md`)
- Analyst → Shot similarity: computes similarity (evidence: `README.md`)
- Analyst → Thread assignment: converts similarity (evidence: `README.md`)
- Analyst → Scene detection: computes scenes (evidence: `README.md`)
- Analyst → Frame access: provides frame access (evidence: `README.md`)
- Shot similarity → Thread assignment: returns scores for (evidence: `README.md`)
- Thread assignment → Thread visualization: visualizes threads (evidence: `README.md`)
- Scene detection → Scene visualization: visualizes scene breaks (evidence: `README.md`)
- Shot events → Episode setup: episode shot data
- Shot similarity → Image comparison: uses image comparison
- Shot similarity → Frame access: reads frames
- Thread assignment → Maximal cliques: finds cliques
- Thread visualization → HTML renderer: renders through
- Scene visualization → HTML renderer: renders through
- Thread visualization → Thread template: uses template
- Scene visualization → Scene template: uses template
