How sony/mapray-js works
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.