# dvt3d/dc-sdk architecture

> Architecture diagram of the GitHub repository dvt3d/dc-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dvt3d/dc-sdk
- Repository: https://github.com/dvt3d/dc-sdk

## Overview

##### Project type and purpose
- DC-SDK is an open-source JavaScript/TypeScript SDK built on Cesium, designed to accelerate the development of 3D WebGIS applications.
- It provides a core “DC” namespace (DC.Viewer, DC.Layer, DC.Overlay, DC.Widget, etc.), dozens of feature modules (animation, chart, effect, event, imagery, material, math, measure, plot, terrain, weather, wind, etc.), theming (SCSS), CLI/build scripts, documentation site, and a gallery of HTML examples.

##### Top-level structure and build/deploy components
- Source: /src – organized by feature areas (modules/, global-api/, libs/, index.js).
- Themes: /src/themes – SCSS for UI widgets.
- Build scripts: gulpfile.js, server.js, package.json, .github/workflows/build.yml.
- Docs site: /docs – VitePress configuration and markdown.
- Examples: /examples – self-contained HTML/JS demos plus assets.
- Distribution: /dist via gulp/webpack/Vite – produces dc.min.js, dc.min.css, and /resources (Cesium assets).

##### Key runtime components (to represent
a. DC Core Loader
- DC.ready() – bootstrap, configures CESIUM_BASE_URL.
b. Viewer
- DC.Viewer – wraps Cesium.Viewer, manages scene, camera, globe, controls.
c. Module Registry
- Feature modules (animation, charts, effects, events, imagery, layers, overlays, material, math, measure, plot, terrain, weather, wind, widget) are lazy-loaded or initialized by Viewer.
d. Cesium Engine
- Core Cesium API (Scene, Entities, Primitives, Camera, DataSources, ImageryProviders, TilingSchemes, etc.)
- Static resources: Assets, Workers, ThirdParty (served from libs/dc-sdk/resources)
e. External Services / Data Providers
- AMap, Baidu, Google, ArcGIS, TDT, Tencent imagery providers
- Data formats: GeoJSON, KML, CZML, I3S, glTF/GLB, 3D Tiles, shapefiles, geojson, turf-based geometry transformations
f. UI Widgets
- Compass, ContextMenu, DistanceLegend, HawkeyeMap, LoadingMask, LocationBar, MapSwitch, Popup, SceneSplit, TilesetSplit, Tooltip, ZoomController

##### Interactions and data flow
1. Build Pipeline (Developer Machine)
- gulp/webpack/Vite compiles /src + SCSS → dc.min.js, dc.min.css
- Copy Cesium static resources → libs/dc-sdk/resources
- Publish to NPM and/or CDN
2. Consumer Application
- import '@dvgis/dc-sdk/dist/dc.min.css' & dc.min.js or install via NPM/Yarn
- Call DC.ready(config) → load Cesium assets from baseUrl
- Instantiate new DC.Viewer({…}) → triggers:
– Module initialization (global APIs, imagery, layers, overlays, etc.)
– Underlying Cesium.Viewer creation
3. Viewer Runtime
- DC modules translate calls to Cesium primitives/entities, shaders (GLSL under /modules/material/shader), data sources, and WebGL operations
- Scene rendered by Cesium’s engine in WebGL canvas
4. Optional interactions
- Events published by DC.Event module
- Widgets manipulate Cesium controls and DOM overlays
- External tile/imagery services fetched over HTTP

##### Architectural patterns and design principles
- Modular architecture – each feature lives in its own folder under /src/modules.
- Facade pattern – DC.Viewer abstracts away Cesium complexity.
- Plugin-style loading – DC.globalApi and DC.config allow extension/custom imagery providers, custom layers, custom materials.
- Separation of concerns – rendering (Cesium), business logic (DC modules), UI (widgets/themes), and documentation/examples.

– Clear, per-component labels (e.g., “DC.Viewer”, “Cesium Engine”, “ImageryProvider Plugin”).
- Blue for SDK internals
- Green for build/deploy infrastructure
- Orange for third-party/Cesium
- Purple for runtime services

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Environment
    subgraph "Developer Environment"
        direction TB
        subgraph "Source (/src)" 
            direction TB
            CoreLoader["DC Core Loader\n(src/index.js)"]:::sdk
            GlobalAPI["Global API\n(src/global-api/index.js)"]:::sdk
            ModuleReg["Module Registry\n(src/modules/index.js)"]:::sdk
            Themes["Themes (SCSS)\n(src/themes/index.scss)"]:::sdk
            subgraph "Feature Modules (/src/modules)"
                direction TB
                Anim["Animation Module"]:::sdk
                Chart["Chart Module"]:::sdk
                Effect["Effect Module"]:::sdk
                EventM["Event Module"]:::sdk
                Imagery["Imagery Module"]:::sdk
                LayerM["Layer Module"]:::sdk
                Overlay["Overlay Module"]:::sdk
                Material["Material Module"]:::sdk
                MathM["Math Utilities"]:::sdk
                Measure["Measure Module"]:::sdk
                Plot["Plot Module"]:::sdk
                Terrain["Terrain Module"]:::sdk
                Weather["Weather Module"]:::sdk
                Wind["Wind Module"]:::sdk
                Widget["UI Widgets Module"]:::sdk
            end
            Libs["Cesium Static Resources\n(src/libs/index.js)"]:::sdk
        end
        subgraph "Build & CI"
            direction TB
            BuildScripts["Build Scripts & CI"]:::build
            DocsSite["Documentation Site\n(docs/.vitepress/config.js)"]:::build
            Examples["Examples Gallery\n(examples/)"]:::build
        end
    end

    %% Distribution
    subgraph "Distribution"
        direction TB
        NPM["NPM Package\n(dc.min.js, dc.min.css)"]:::build
        Resources["Resources Folder\n(Cesium assets)"]:::sdk
    end

    %% Consumer Application
    Consumer["Consumer Application"]:::external

    %% Runtime Components
    subgraph "Runtime"
        direction TB
        Ready["DC.ready()"]:::sdk
        Viewer["DC.Viewer"]:::sdk
        subgraph "Viewer Runtime"
            direction TB
            ModuleRegRuntime["Module Registry"]:::sdk
            FeatureMods["Feature Modules"]:::sdk
            CesiumEngine["Cesium Engine"]:::cesium
            UIWidgets["UI Widgets"]:::sdk
            ExternalServices["External Services\n(Imagery Providers)"]:::service
        end
    end

    %% Data Flow
    BuildScripts -->|build & publish| NPM
    BuildScripts -->|copy resources| Resources
    NPM -->|install/import| Consumer
    Resources -->|serve assets| Consumer

    Consumer -->|call| Ready
    Ready -->|initializes| Viewer
    Viewer -->|registers| ModuleRegRuntime
    ModuleRegRuntime -->|loads| FeatureMods
    Viewer -->|uses| UIWidgets
    FeatureMods -->|render calls| CesiumEngine
    CesiumEngine -->|HTTP fetch| ExternalServices

    %% Click Events
    click CoreLoader "https://github.com/dvt3d/dc-sdk/blob/master/src/index.js"
    click GlobalAPI "https://github.com/dvt3d/dc-sdk/blob/master/src/global-api/index.js"
    click ModuleReg "https://github.com/dvt3d/dc-sdk/blob/master/src/modules/index.js"
    click Themes "https://github.com/dvt3d/dc-sdk/blob/master/src/themes/index.scss"
    click Anim "https://github.com/dvt3d/dc-sdk/blob/master/src/modules/animation/index.js"
    click Chart "https://github.com/dvt3d/dc-sdk/blob/master/src/modules/chart/ChartLayer.js"
    click Effect "https://github.com/dvt3d/dc-sdk/blob/master/src/modules/effect/index.js"
    click EventM "https://github.com/dvt3d/dc-sdk/blob/master/src/modules/event/index.js"
    click Imagery "https://github.com/dvt3d/dc-sdk/blob/master/src/modules/imagery/index.js"
    click LayerM "https://github.com/dvt3d/dc-sdk/blob/master/src/modules/layer/index.js"
    click Overlay "https://github.com/dvt3d/dc-sdk/blob/master/src/modules/overlay/index.js"
    click Material "https://github.com/dvt3d/dc-sdk/blob/master/src/modules/material/index.js"
    click MathM "https://github.com/dvt3d/dc-sdk/blob/master/src/modules/math/index.js"
    click Measure "https://github.com/dvt3d/dc-sdk/blob/master/src/modules/measure/index.js"
    click Plot "https://github.com/dvt3d/dc-sdk/blob/master/src/modules/plot/Plot.js"
    click Terrain "https://github.com/dvt3d/dc-sdk/blob/master/src/modules/terrain/index.js"
    click Weather "https://github.com/dvt3d/dc-sdk/blob/master/src/modules/weather/Weather.js"
    click Wind "https://github.com/dvt3d/dc-sdk/blob/master/src/modules/wind/WindLayer.js"
    click Widget "https://github.com/dvt3d/dc-sdk/blob/master/src/modules/widget/index.js"
    click Libs "https://github.com/dvt3d/dc-sdk/blob/master/src/libs/index.js"
    click BuildScripts "https://github.com/dvt3d/dc-sdk/blob/master/package.json"
    click DocsSite "https://github.com/dvt3d/dc-sdk/blob/master/docs/.vitepress/config.js"
    click Examples "https://github.com/dvt3d/dc-sdk/tree/master/examples/"

    %% Styles
    classDef build fill:#8FBC8F,stroke:#333,stroke-width:1px,color:#000
    classDef sdk fill:#87CEEB,stroke:#333,stroke-width:1px,color:#000
    classDef cesium fill:#FFA500,stroke:#333,stroke-width:1px,color:#000
    classDef service fill:#9370DB,stroke:#333,stroke-width:1px,color:#000
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px,color:#000
```
