# jeremyheleine/photo-sphere-viewer architecture

> Architecture diagram of the GitHub repository jeremyheleine/photo-sphere-viewer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jeremyheleine/photo-sphere-viewer
- Repository: https://github.com/jeremyheleine/photo-sphere-viewer

## Overview

##### Main Components and Their Roles
- PhotoSphereViewer Core: At the heart of the system is the main module (src/PhotoSphereViewer.js). This component orchestrates loading the panorama, setting up the Three.js scene, handling canvas rendering, and managing user interactions.
- Navigation Bar Elements: In support to the viewer, there are dedicated components (src/PSVNavBar.js and src/PSVNavBarButton.js) that form the navigation controls. These allow the user to interact (rotate, zoom, etc.) with the panorama.
- Helper Modules: Components like src/sphoords.js likely provide dedicated functions to convert or manage spherical coordinates essential to map the panorama correctly.

##### Relationships and Interactions
- The PhotoSphereViewer core ties all components together:
- It uses the Three.js library to render the panorama onto a canvas.
- It instantiates and coordinates with the Navigation Bar components to provide user controls.
- It calls helper methods from sphoords.js to compute and adjust coordinates as needed.
passed during initialization.

##### Architectural Patterns
- Modular Design: The library splits responsibilities into separate modules (core viewer, navbar, helper functions), reflecting a modular, single-responsibility design.
- Integration with Third-party Libraries: The dependency on Three.js is a key pattern – separating rendering (handled by Three.js) from application-level logic in the viewer.
- Client-Side Rendering: All components run in the browser environment and interact directly with HTML elements. This is a clear “browser-based library” architecture.

##### Relevant Technologies and Frameworks
- JavaScript (ES5/ES6) is used to build the components.
- Three.js provides the WebGL-based rendering engine.
- The library is intended to be embedded into web pages via script tags that load photo-sphere-viewer.min.js and three.min.js.

##### Customization for the Project
- Since this is a JavaScript library (not a full-stack web app), omit backend services like databases or API gateways. Instead, focus on internal client-side components.
- Separation of concerns and interactions among the viewer core, navigation elements, and external rendering engine.
- Document how the library is integrated into an HTML page, with clear separation between the library’s API (the object creation and options supplied) and the underlying rendering flow.

- A central “PhotoSphereViewer” component that is responsible for panorama display, user interaction, and configuration.
- Connected sub-components for navigation (navbar and buttons) and coordinate management.
- An external dependency block for Three.js, with annotations on how it interacts with the core.
- Annotations for the configuration parameters that help configure these components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Internal Components (Client-side Modules)
    core["PhotoSphereViewer Core"]:::internal
    navbar["Navigation Bar (PSVNavBar)"]:::internal
    navButton["Navigation Bar Button (PSVNavBarButton)"]:::internal
    helper["Spherical Coordinates Helper (sphoords.js)"]:::internal
    dom["DOM Container (HTML Element)"]:::ui
    examples["Usage Examples & Testing"]:::ui

    %% External Dependency
    threejs["Three.js Library"]:::external

    %% Relationships and Data Flow (Vertical Layout)
    core -->|"calls rendering APIs"| threejs
    core -->|"sendsUserInputEvents"| navbar
    navbar -->|"triggersButtonEvents"| navButton
    core -->|"callsCoordinateTransformations"| helper
    core -->|"initializesInto"| dom
    examples -->|"demonstratesUsageOf"| core

    %% Click Events for Component Mapping
    click core "https://github.com/jeremyheleine/photo-sphere-viewer/blob/master/src/PhotoSphereViewer.js"
    click navbar "https://github.com/jeremyheleine/photo-sphere-viewer/blob/master/src/PSVNavBar.js"
    click navButton "https://github.com/jeremyheleine/photo-sphere-viewer/blob/master/src/PSVNavBarButton.js"
    click helper "https://github.com/jeremyheleine/photo-sphere-viewer/blob/master/src/sphoords.js"
    click examples "https://github.com/jeremyheleine/photo-sphere-viewer/tree/master/examples/"

    %% Styles for Color Coding
    classDef internal fill:#cce5ff,stroke:#339af0,stroke-width:2px;
    classDef external fill:#d4edda,stroke:#28a745,stroke-width:2px;
    classDef ui fill:#fff3cd,stroke:#ffc107,stroke-width:2px;
```
