# sony/mapray-js architecture

> Architecture diagram of the GitHub repository sony/mapray-js, 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/sony/mapray-js
- Repository: https://github.com/sony/mapray-js

## Overview

This project is maprayJS—a JavaScript library that provides high-quality interactive 3D globes and digital twin capabilities on the web using WebGL. Based on the file tree and README, the project serves as a core engine for rendering globes, handling geospatial data, and providing associated UI components as an add-on (maprayui). Its structure divides responsibilities among core functionalities, UI integration, tests, examples, and debugging tools.

##### Main Components Identification
- Core Rendering Engine (mapray core):
- Located in the “packages/mapray” directory. This is the heart of the system and includes modules for rendering (Viewer, Scene, Camera, WebGL environment), geospatial math, and various entities (e.g., models, meshes, point clouds).
- It also contains numerous lower-level utilities including shader programs, animation modules, and support for 3D tile formats, dem providers, and image providers.
- UI Components (maprayui):
- Found in the “packages/ui” directory. This component provides APIs and UI elements that integrate with the core to enhance interactivity and toolsets for users.
- External Data Providers and Services:
- Providers such as StandardImageProvider and CloudDemProvider are used to fetch remote map data (e.g., terrain data, imagery). The README emphasizes that an access token is needed to connect to the Mapray Cloud service.
- Examples, Debug, and Test Applications:
- Directories like “examples”, “debug”, and “browser-test” showcase application use cases, serve as test harnesses, and illustrate various features of the engine (e.g., 3D entities, camera controls, animations).

##### Relationships and Interactions
- The Viewer is the primary interface that ties everything together. It communicates with:
- The Rendering Engine: for drawing and updating the 3D globe scene.
- Data Providers: to retrieve terrain imagery and elevation data.
- UI Components: which intercept user input/control and provide interactive overlays.
- The Core Engine is structured in a modular way where each module (like Camera, Scene, Shader, Animation) interacts through well-defined interfaces and dependency injection.
- External services (Mapray Cloud) and third-party data providers are integrated via provider modules that supply image tiles and digital elevation models.

##### Architectural Patterns and Design Principles
- Modular architecture: The system is split into multiple packages and modules (core, UI, debug, examples) to maximize reusability and maintainability.
- Separation of concerns: Distinct responsibilities are allocated to rendering, data fetching, UI handling, and testing.
- Extensibility: The design supports various external resource integrations (e.g., GLTF, B3d tiles, vector data) and is easily extended/customized via new modules or providers.
- Utilization of WebGL and shader-based rendering: The presence of many shader files indicates a clean separation between the graphics pipeline and other logic modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation/UI Layer
    subgraph "Presentation/UI Layer"
        Viewer("Viewer"):::viewer
        ui_components("UI Components"):::ui
    end

    %% Core Engine Layer
    subgraph "Core Engine Layer"
        core_engine("Rendering Engine/Scene Management"):::core
        utilities("Utility Modules"):::core
        shaders("Shader Modules"):::core
    end

    %% Data & Service Layer
    subgraph "Data & Service Layer"
        standard_image_provider("StandardImageProvider"):::data
        cloud_dem_provider("CloudDemProvider"):::data
        mapray_cloud("Mapray Cloud Service"):::external
    end

    %% Testing & Examples
    subgraph "Testing & Examples"
        examples_node("Examples"):::test
        browser_test_node("Browser Tests"):::test
        debug_node("Debug Tools"):::test
    end

    %% Relationships and Data Flow
    Viewer -->|"controls"| core_engine
    Viewer -->|"controls"| ui_components
    ui_components -->|"interacts"| core_engine
    core_engine -->|"includes"| utilities
    core_engine -->|"includes"| shaders
    core_engine -->|"fetches"| standard_image_provider
    core_engine -->|"fetches"| cloud_dem_provider
    mapray_cloud -->|"supplies"| standard_image_provider
    mapray_cloud -->|"supplies"| cloud_dem_provider

    %% Click Events for Component Mapping
    click core_engine "https://github.com/sony/mapray-js/tree/main/packages/mapray"
    click ui_components "https://github.com/sony/mapray-js/tree/main/packages/ui"
    click standard_image_provider "https://github.com/sony/mapray-js/blob/main/packages/mapray/src/StandardImageProvider.ts"
    click cloud_dem_provider "https://github.com/sony/mapray-js/blob/main/packages/mapray/src/CloudDemProvider.ts"
    click examples_node "https://github.com/sony/mapray-js/tree/main/examples"
    click browser_test_node "https://github.com/sony/mapray-js/tree/main/browser-test"
    click debug_node "https://github.com/sony/mapray-js/tree/main/debug"

    %% Styles
    classDef core fill:#a6cee3,stroke:#1f78b4,stroke-width:2px;
    classDef ui fill:#b2df8a,stroke:#33a02c,stroke-width:2px;
    classDef data fill:#fdbf6f,stroke:#ff7f00,stroke-width:2px;
    classDef external fill:#f4a582,stroke:#d6604d,stroke-width:2px;
    classDef test fill:#ffff99,stroke:#ffcc00,stroke-width:2px;
    classDef viewer fill:#ccebc5,stroke:#66c2a5,stroke-width:2px;
```
