@pirireis/webglobeplugins 0.17.0 → 1.0.2

package/semiplugins/shape-on-terrain/{circle-plugin.js → circle-plugin.ts}

@@ -1,444 +1,588 @@
-import { LineStripProgramCache } from "../../programs/line-on-globe/linestrip/linestrip";
-import { BufferManager, BufferOrchestrator } from "../../util/account/single-attribute-buffer-management/index";
-import { CameraUniformBlockTotemCache } from "../../programs/totems/camerauniformblock";
-import { createBufferAndReadInfo } from "../../util/gl-util/buffer/attribute-loader";
-import * as CircleMethods from "../../Math/circle";
-import * as CircleCDF from "../../Math/circle-cdf-points";
-import * as vec3 from "../../Math/vec3";
-import { globe3Dcoordinates, globe2Dcoordinates } from "../../Math/methods";
-import { StaticDynamicStrategy, StaticDynamicState } from "../../util/build-strategy/static-dynamic";
-import { WORLD_RADIUS_3D, WORLD_RADIUS_MERCATOR } from "../../Math/constants";
-import { opacityCheck } from "../../util/check/typecheck";
-import { FrameCounterTrigger } from "../../util/frame-counter-trigger";
-const ACTIVATE_DYNAMIC_STRATEGY_AT_LEVEL = 8;
-const CIRCLE_POINTS_COUNT_HALF = 65; // Half of the points plus one for the reflection
-const CIRCLE_POINTS_COUNT = CIRCLE_POINTS_COUNT_HALF * 2 - 1; // Number of points to approximate the circle
-const DENSE_PART_SAMPLE_RATIO = 0.80; // Ratio of the dense part of the circle
-const STRENGTH_FACTOR = 2; // Strength factor for the circle sampling
-// --- TUNABLE PARAMETERS ---
-const ATTRACTION_LEVELS = 7;
-// Radius below which the most even sampling (level 0) is always used.
-const MIN_RADIUS_KM = 5000;
-// The radius (km) at the center of the transition for the reference LOD.
-// DECREASE this to make mid-sized circles use uneven samples EARLIER.
-const MID_TRANSITION_RADIUS_KM = WORLD_RADIUS_MERCATOR * 0.85;
-const RADIUS_INFLUENCE = 0.55; // How much the radius influences the transition.
-// The reference LOD for the transition.
-const MID_TRANSITION_LOD = 10;
-// How much LOD shifts the curve. Higher means LOD has more influence.
-const LOD_INFLUENCE = 0.385;
-// Steepness of the transition. Higher value = more abrupt switch.
-// DECREASE this to make large circles transition to higher tiers SLOWER.
-const TRANSITION_STEEPNESS = 0.77;
-/**
- * @param lod The current zoom level.
- * @param radiusMeters The circle's radius in meters.
- * @returns An integer level from 0 to ATTRACTION_LEVELS - 1.
- */
-const defineStregthLevel = (lod, radiusMeters) => {
-    const radiusKm = radiusMeters;
-    // return ATTRACTION_LEVELS - 1;
-    // 1. Enforce a minimum radius for even sampling.
-    if (radiusKm < MIN_RADIUS_KM) {
-        return 0;
-    }
-    // 2. Combine radius and LOD into a single variable.
-    const log_r_mid = Math.log(MID_TRANSITION_RADIUS_KM);
-    const log_r = Math.log(radiusKm);
-    const combined_input = RADIUS_INFLUENCE * (log_r - log_r_mid) + LOD_INFLUENCE * (lod - MID_TRANSITION_LOD);
-    // 3. Apply the logistic (sigmoid) function to get a strength value [0, 1].
-    const strength_factor = 1.0 / (1.0 + Math.pow(2.4, -TRANSITION_STEEPNESS * combined_input));
-    // 4. Scale the result to the available attraction levels and clamp.
-    const level = Math.floor(strength_factor * ATTRACTION_LEVELS);
-    return Math.min(level, ATTRACTION_LEVELS - 1);
-};
-const AnglesStash = CircleCDF.createCummulativeTemplateStash(ATTRACTION_LEVELS, CIRCLE_POINTS_COUNT_HALF, DENSE_PART_SAMPLE_RATIO, STRENGTH_FACTOR);
-const _colorArray = new Float32Array(4 * CIRCLE_POINTS_COUNT); // Used to store the color for each circle
-export class CircleOnTerrainPlugin {
-    id;
-    globe = null;
-    gl = null;
-    lineProgram = null;
-    bufferManagersMap = new Map();
-    bufferOrchestrator = new BufferOrchestrator();
-    circleMap = new Map();
-    _cameraUniformBlock = null;
-    _freed = false;
-    _circleUBOHandler = null;
-    _opacity = 1;
-    _vao = null;
-    _dobuild = true; // This is used to trigger the build of circles when the camera position changes.
-    _frameCounterTrigger = null;
-    _staticDynamicStrategy = null;
-    _options = {
-        variativeColorsOn: false,
-        defaultColor: [0.1, 0.1, 0.1, 1], // Default color in RGBA format
-        defaultHeightFromGroundIn3D: 30.0,
-        isMSL: false
-    };
-    _textDataPreAdaptor = undefined;
-    constructor(id, styleOptions = null) {
-        this.id = id;
-        if (styleOptions) {
-            this._options = { ...this._options, ...styleOptions };
-        }
-    }
-    init(globe, gl) {
-        this.globe = globe;
-        this.gl = gl;
-        // Initialize the program cache for line strip rendering.
-        this.lineProgram = LineStripProgramCache.get(globe);
-        const g2D = globe2Dcoordinates(globe);
-        // Initialize with a reasonable initial capacity to prevent buffer size issues
-        const initialCapacity = 100; // Start with capacity for 100 circles
-        this.bufferManagersMap.set("position3d", {
-            bufferManager: new BufferManager(gl, (CIRCLE_POINTS_COUNT + 1) * 3, { initialCapacity }), // plus 1 is for butting linestrips
-            adaptor: (item) => {
-                const { longLatArr, height = this._options.defaultHeightFromGroundIn3D, msl = this._options.isMSL } = item;
-                const result = globe3Dcoordinates(globe, longLatArr, height, msl, { paddingCount: 1, paddingValue: NaN });
-                return result;
-            }
-        });
-        this.bufferManagersMap.set("position2d", {
-            bufferManager: new BufferManager(gl, (CIRCLE_POINTS_COUNT + 1) * 2, { initialCapacity }),
-            adaptor: (item) => {
-                const { longLatArr } = item;
-                const result = g2D(longLatArr, { paddingCount: 1, paddingValue: NaN });
-                return result;
-            }
-        });
-        if (this._options.variativeColorsOn) {
-            this.bufferManagersMap.set("color", {
-                bufferManager: new BufferManager(gl, (CIRCLE_POINTS_COUNT + 1) * 4, { initialCapacity }),
-                adaptor: (item) => {
-                    if (item.color) {
-                        for (let i = 0; i < CIRCLE_POINTS_COUNT; i++) {
-                            _colorArray.set(item.color, i * 4);
-                        }
-                    }
-                    else {
-                        for (let i = 0; i < CIRCLE_POINTS_COUNT; i++) {
-                            _colorArray.set(this._options.defaultColor, i * 4);
-                        }
-                    }
-                    return _colorArray;
-                }
-            });
-        }
-        this._vao = this.lineProgram.createVAO(createBufferAndReadInfo(this.bufferManagersMap.get("position3d")?.bufferManager.buffer), createBufferAndReadInfo(this.bufferManagersMap.get("position2d")?.bufferManager.buffer), this._options.variativeColorsOn ?
-            createBufferAndReadInfo(this.bufferManagersMap.get("color")?.bufferManager.buffer) : null);
-        this._circleUBOHandler = this.lineProgram.createUBO();
-        this.setDefaultColor(this._options.defaultColor);
-        this._cameraUniformBlock = CameraUniformBlockTotemCache.get(globe);
-        this._staticDynamicStrategy = new StaticDynamicStrategy(globe, ACTIVATE_DYNAMIC_STRATEGY_AT_LEVEL, () => {
-            this.__buildStaticCircles();
-        });
-        this._frameCounterTrigger = new FrameCounterTrigger(globe, 15, 1000, (globeChanges) => {
-            if (this._freed)
-                return;
-            this._buildCircles();
-        });
-    }
-    increaseSpace(amount) {
-        if (this._freed) {
-            console.warn("Plugin is freed, cannot increase space");
-            return;
-        }
-        if (this.globe === null) {
-            console.warn("Globe is not initialized.");
-            return;
-        }
-        if (typeof amount !== "number" || amount <= 0) {
-            console.warn("Invalid amount, must be a positive number");
-            return;
-        }
-        this.bufferOrchestrator.ensureSpace(amount, this.bufferManagersMap);
-    }
-    insertBulk(circles) {
-        if (this._freed)
-            return;
-        if (!this.globe || !this.gl || !this.lineProgram || !this.bufferOrchestrator ||
-            !this.bufferManagersMap || !this._vao || !this._circleUBOHandler) {
-            throw new Error("Plugin not initialized properly");
-        }
-        const keys = [];
-        let newItemCount = 0;
-        for (const circleInput of circles) {
-            if (circleInput.key == null || circleInput.center == null || circleInput.radius == null) {
-                console.warn(`CircleOnTerrainPlugin: Circle input is missing required properties: ${circleInput.radius} or ${circleInput.center} or ${circleInput.key}`);
-                continue;
-            }
-            if (circleInput.radius <= 0) {
-                // console.warn(`CircleOnTerrainPlugin: Circle ${circleInput.key} has non-positive radius ${circleInput.radius}. Skipping.`);
-                continue;
-            }
-            keys.push(circleInput.key);
-            if (!this.circleMap.has(circleInput.key)) {
-                newItemCount++;
-            }
-            const circleForAzimuthCalc = CircleMethods.createCircleClosestAzimuthAngleProperties(circleInput);
-            this.circleMap.set(circleInput.key, [circleInput, circleForAzimuthCalc]);
-        }
-        this.bufferOrchestrator.ensureSpace(newItemCount, this.bufferManagersMap);
-        this._buildCircles(keys);
-        if (this._options.variativeColorsOn) {
-            this.__fillColor(keys);
-        }
-        this.globe.DrawRender();
-    }
-    updateColors(keyColorCouples, drawRender = true) {
-        if (this._freed) {
-            console.warn("Plugin is freed, cannot increase space");
-            return;
-        }
-        if (this.globe === null) {
-            console.warn("Globe is not initialized.");
-            return;
-        }
-        if (this._options.variativeColorsOn === false) {
-            console.warn("VariativeColors are not enabled");
-            return;
-        }
-        for (const { key, color } of keyColorCouples) {
-            const [circleInput] = this.circleMap.get(key) || [];
-            if (circleInput) {
-                circleInput.color = color;
-                this.__fillColor([key]);
-            }
-            else {
-                console.warn(`Circle key ${key} not found in circleMap.`);
-            }
-        }
-        if (drawRender) {
-            this.globe.DrawRender();
-        }
-    }
-    deleteBulk(keys) {
-        if (this._freed)
-            return;
-        if (!this.globe || !this.gl || !this.lineProgram || !this.bufferOrchestrator ||
-            !this.bufferManagersMap || !this._vao || !this._circleUBOHandler) {
-            throw new Error("Plugin not initialized properly");
-        }
-        this.bufferOrchestrator.deleteBulk(keys, this.bufferManagersMap);
-        for (const key of keys) {
-            if (this.circleMap.has(key)) {
-                this.circleMap.delete(key);
-            }
-            else {
-                console.warn(`CircleOnTerrainPlugin: Circle ${key} not found in circleMap. Cannot delete.`);
-            }
-        }
-    }
-    setPluginOpacity(opacity, drawRender = false) {
-        if (!this.globe || !this.gl) {
-            console.warn("Globe or WebGL context is not initialized.");
-            return;
-        }
-        opacityCheck(opacity);
-        this._opacity = opacity;
-        if (drawRender) {
-            this.globe.DrawRender();
-        }
-    }
-    setElevationMode(mode) {
-        switch (mode) {
-            case "msl":
-                this._options.isMSL = true;
-                break;
-            case "agl":
-                this._options.isMSL = false;
-                break;
-            default:
-                throw new Error(`Unknown elevation mode: ${mode}`);
-        }
-        this._buildCircles();
-        this.globe?.DrawRender();
-    }
-    setDefaultColor(color, drawRender = false) {
-        if (!this.globe || !this.gl) {
-            console.warn("Globe or WebGL context is not initialized.");
-            return;
-        }
-        this._circleUBOHandler?.updateSingle("u_color", new Float32Array(color));
-        if (drawRender) {
-            this.globe.DrawRender();
-        }
-    }
-    updateCoordinates(items) {
-        if (this._freed) {
-            console.warn("CircleOnTerrainPlugin is freed, cannot update coordinates");
-            return;
-        }
-        if (this.globe === null) {
-            console.warn("Globe is not initialized, cannot update coordinates");
-            return;
-        }
-        const updateKeys = [];
-        for (const item of items) {
-            const { key, center, radius } = item;
-            const [circleInput] = this.circleMap.get(key) || [];
-            if (circleInput) {
-                circleInput.center = center;
-                circleInput.radius = radius;
-                updateKeys.push(key);
-            }
-            else {
-                console.warn(`Circle key ${key} not found in circleMap.`);
-                continue;
-            }
-        }
-        this._buildCircles(updateKeys);
-        this.globe.DrawRender();
-    }
-    // IMPLICIT METHODS
-    __fillColor(subSetIDs) {
-        if (!this._options.variativeColorsOn)
-            return;
-        const wrapper = [null];
-        for (const key of subSetIDs) {
-            const [circleInput,] = this.circleMap.get(key) || [];
-            if (circleInput) {
-                wrapper[0] = circleInput;
-                this.bufferOrchestrator.insertBulk(wrapper, this.bufferManagersMap, ["color"]);
-            }
-        }
-    }
-    _buildCircles(subSetIDs = null) {
-        // @ts-ignore
-        this._staticDynamicStrategy?.updateState();
-        const state = this._staticDynamicStrategy?.getState();
-        if (state === StaticDynamicState.DYNAMIC) {
-            this.__buildDynamicCircles(subSetIDs);
-        }
-        else if (subSetIDs || state === StaticDynamicState.TO_STATIC) {
-            this.__buildStaticCircles(subSetIDs);
-        }
-    }
-    __buildDynamicCircles(subSetIDs = null) {
-        const { globe, gl, _cameraUniformBlock, lineProgram, bufferOrchestrator, bufferManagersMap, circleMap } = this;
-        if (!globe || !gl || !_cameraUniformBlock || !lineProgram ||
-            !bufferOrchestrator || !bufferManagersMap || !circleMap)
-            throw new Error("Plugin not initialized properly");
-        // unoptimized.. resets all circles.
-        // bufferOrchestrator.resetWithCapacity(bufferManagersMap, circleMap.size);
-        // Prepare the data for the buffers
-        const data = [{
-                key: "",
-                longLatArr: [],
-                height: null,
-                msl: null
-            }];
-        const lookAtPosition = _cameraUniformBlock.getLookAtVector();
-        const cameraPosition = _cameraUniformBlock.getNormalizedCameraVector();
-        vec3.divideScalar(cameraPosition, cameraPosition, WORLD_RADIUS_3D);
-        vec3.add(cameraPosition, cameraPosition, lookAtPosition);
-        vec3.normalize(cameraPosition, cameraPosition);
-        const currentLOD = globe.api_GetCurrentLODWithDecimal();
-        const circlePointsLongLat = new Float64Array((CIRCLE_POINTS_COUNT) * 2);
-        let keys;
-        if (!subSetIDs || subSetIDs.length === 0) {
-            keys = Array.from(this.circleMap.keys());
-            // bufferOrchestrator.resetWithCapacity(bufferManagersMap, circleMap.size);
-        }
-        else {
-            keys = subSetIDs;
-        }
-        for (const key of keys) {
-            const [{ radius, center, height = null, msl = null }, circleForAzimuthCalc] = this.circleMap.get(key);
-            const closestAzimuthAngle = CircleMethods.closestAzimuthAngle(circleForAzimuthCalc, cameraPosition);
-            const stregthLevel = defineStregthLevel(currentLOD, radius);
-            if (typeof stregthLevel !== "number") {
-                console.warn(`CircleOnTerrainPlugin: Circle ${key} has invalid strength level for current LOD ${currentLOD}. Skipping., radius: ${radius}, stregthLevel: ${stregthLevel}`);
-                continue;
-            }
-            if (stregthLevel < 0) {
-                console.warn(`CircleOnTerrainPlugin: Circle ${key} has too small radius for current LOD ${currentLOD}. Skipping., radius: ${radius}, stregthLevel: ${stregthLevel}`);
-                continue;
-            }
-            const templateAngles = AnglesStash[stregthLevel];
-            CircleCDF.globeFindPointByPolarHalfCircle(circlePointsLongLat, globe, center[0], center[1], radius, closestAzimuthAngle, templateAngles);
-            data[0].key = key;
-            data[0].longLatArr = circlePointsLongLat;
-            data[0].height = height;
-            data[0].msl = msl;
-            // Add to buffer orchestrator
-            this.bufferOrchestrator.insertBulk(data, bufferManagersMap, [
-                this.globe?.api_GetCurrentGeometry() === 0 ? "position3d" : "position2d",
-            ]);
-        }
-    }
-    // this will be used to build static circles, which are not affected by camera position or LOD.
-    // LOD < 8 or something
-    __buildStaticCircles(subSetIDs = null) {
-        const { globe, gl, _cameraUniformBlock, lineProgram, bufferOrchestrator, bufferManagersMap, circleMap } = this;
-        if (!globe || !gl || !_cameraUniformBlock || !lineProgram ||
-            !bufferOrchestrator || !bufferManagersMap || !circleMap)
-            throw new Error("Plugin not initialized properly");
-        const datas = [];
-        // ensure buffer orchestrotrator have enough capacity
-        // all circles are build with even sampling, AttractionLevel = 0
-        const templateAngles = AnglesStash[0];
-        const zeroRotation = 0;
-        let keys;
-        if (!subSetIDs || subSetIDs.length === 0) {
-            keys = Array.from(this.circleMap.keys());
-            // bufferOrchestrator.resetWithCapacity(bufferManagersMap, circleMap.size);
-        }
-        else {
-            keys = subSetIDs;
-        }
-        for (let key of keys) {
-            if (!this.circleMap.has(key)) {
-                console.warn(`CircleOnTerrainPlugin: Circle ${key} not found in circleMap.`);
-                continue;
-            }
-            const [{ radius, center, height = null, color = null, msl = undefined },] = this.circleMap.get(key);
-            const circlePointsLongLat = new Float64Array((CIRCLE_POINTS_COUNT) * 2);
-            CircleCDF.globeFindPointByPolarHalfCircle(circlePointsLongLat, globe, center[0], center[1], radius, zeroRotation, templateAngles);
-            datas.push({
-                key,
-                longLatArr: circlePointsLongLat,
-                height,
-                color: color || this._options.defaultColor,
-                msl
-            });
-        }
-        this.bufferOrchestrator.insertBulk(datas, bufferManagersMap, [this.globe?.api_GetCurrentGeometry() === 0 ? "position3d" : "position2d"]);
-    }
-    // GLOBE API INTERFACE
-    draw3D() {
-        const { _freed, globe, gl, lineProgram, bufferOrchestrator, bufferManagersMap, _vao, _circleUBOHandler } = this;
-        if (_freed || !globe || !gl || !lineProgram || !bufferOrchestrator ||
-            !bufferManagersMap || !_vao || !_circleUBOHandler) {
-            return;
-        }
-        // if (globe.api_IsScreenMoving())
-        this._frameCounterTrigger?.trigger();
-        // this._buildCircles();
-        const drawOptions = {
-            drawRange: {
-                first: 0,
-                count: bufferOrchestrator.length * (CIRCLE_POINTS_COUNT + 1), // plus 1 is for cutting linestrips
-            },
-        };
-        gl.disable(gl.DEPTH_TEST);
-        lineProgram.draw(_vao, drawOptions, this._opacity, _circleUBOHandler);
-        gl.enable(gl.DEPTH_TEST);
-    }
-    free() {
-        if (this._freed)
-            return;
-        this._freed = true;
-        if (this.lineProgram) {
-            LineStripProgramCache.release(this.lineProgram);
-            this.lineProgram = null;
-        }
-        this.circleMap.clear();
-        this.bufferManagersMap.forEach(({ bufferManager }) => {
-            bufferManager.free();
-        });
-        this.bufferManagersMap.clear();
-        CameraUniformBlockTotemCache.release(this.globe);
-    }
-}
+
+import { SemiPluginInterface } from "../interface";
+import { LineStripProgramCache, LineProgram } from "../../programs/line-on-globe/linestrip/linestrip";
+import { BufferManagersMap, BufferManager, BufferOrchestrator } from "../../util/account/single-attribute-buffer-management/index";
+import { CameraUniformBlockTotem, CameraUniformBlockTotemCache } from "../../programs/totems/camerauniformblock";
+import { DrawRangeIndexParams, Color, UBOHandler, ElevationMode, UpdateColor } from "../../types";
+import { PluginInterface, Globe, Meter, LongLatDegree } from "../../types";
+import { createBufferAndReadInfo } from "../../util/gl-util/buffer/attribute-loader";
+import { Circle, CircleClosestAzimuthAngleProperties } from "../../Math/types";
+import * as CircleMethods from "../../Math/circle";
+import * as CircleCDF from "../../Math/circle-cdf-points";
+import * as vec3 from "../../Math/vec3";
+import { globe3Dcoordinates, globe2Dcoordinates } from "../../Math/methods";
+import { StaticDynamicStrategy, StaticDynamicState } from "../../util/build-strategy/static-dynamic";
+import { WORLD_RADIUS_3D, WORLD_RADIUS_MERCATOR } from "../../Math/constants";
+import { opacityCheck } from "../../util/check/typecheck";
+import { FrameCounterTrigger } from "../../util/frame-counter-trigger";
+const ACTIVATE_DYNAMIC_STRATEGY_AT_LEVEL = 8;
+
+const CIRCLE_POINTS_COUNT_HALF = 65; // Half of the points plus one for the reflection
+const CIRCLE_POINTS_COUNT = CIRCLE_POINTS_COUNT_HALF * 2 - 1; // Number of points to approximate the circle
+const DENSE_PART_SAMPLE_RATIO = 0.80; // Ratio of the dense part of the circle
+const STRENGTH_FACTOR = 2; // Strength factor for the circle sampling
+// --- TUNABLE PARAMETERS ---
+
+const ATTRACTION_LEVELS = 7;
+// Radius below which the most even sampling (level 0) is always used.
+const MIN_RADIUS_KM = 5000;
+// The radius (km) at the center of the transition for the reference LOD.
+// DECREASE this to make mid-sized circles use uneven samples EARLIER.
+const MID_TRANSITION_RADIUS_KM = WORLD_RADIUS_MERCATOR * 0.85;
+const RADIUS_INFLUENCE = 0.55; // How much the radius influences the transition.
+// The reference LOD for the transition.
+const MID_TRANSITION_LOD = 10;
+// How much LOD shifts the curve. Higher means LOD has more influence.
+const LOD_INFLUENCE = 0.385;
+// Steepness of the transition. Higher value = more abrupt switch.
+// DECREASE this to make large circles transition to higher tiers SLOWER.
+const TRANSITION_STEEPNESS = 0.77;
+
+/**
+ * @param lod The current zoom level.
+ * @param radiusMeters The circle's radius in meters.
+ * @returns An integer level from 0 to ATTRACTION_LEVELS - 1.
+ */
+const defineStregthLevel = (lod: number, radiusMeters: number): number => {
+    const radiusKm = radiusMeters;
+    // return ATTRACTION_LEVELS - 1;
+    // 1. Enforce a minimum radius for even sampling.
+    if (radiusKm < MIN_RADIUS_KM) {
+        return 0;
+    }
+
+    // 2. Combine radius and LOD into a single variable.
+    const log_r_mid = Math.log(MID_TRANSITION_RADIUS_KM);
+    const log_r = Math.log(radiusKm);
+    const combined_input = RADIUS_INFLUENCE * (log_r - log_r_mid) + LOD_INFLUENCE * (lod - MID_TRANSITION_LOD);
+
+    // 3. Apply the logistic (sigmoid) function to get a strength value [0, 1].
+    const strength_factor = 1.0 / (1.0 + Math.pow(2.4, -TRANSITION_STEEPNESS * combined_input));
+
+    // 4. Scale the result to the available attraction levels and clamp.
+    const level = Math.floor(strength_factor * ATTRACTION_LEVELS);
+    return Math.min(level, ATTRACTION_LEVELS - 1);
+}
+
+const AnglesStash = CircleCDF.createCummulativeTemplateStash(
+    ATTRACTION_LEVELS,
+    CIRCLE_POINTS_COUNT_HALF,
+    DENSE_PART_SAMPLE_RATIO,
+    STRENGTH_FACTOR
+)
+
+
+
+export type CircleInput = {
+    key: string;
+    center: LongLatDegree;
+    radius: Meter;
+    height?: Meter | null;
+    color?: Color; // Optional color for the circle
+    msl?: boolean | null;
+};
+
+
+
+export type CircleOnTerrainPluginOptions = {
+    defaultHeightFromGroundIn3D?: number;
+    variativeColorsOn?: boolean;
+    defaultColor: Color; // Default color in RGBA format
+    isMSL: boolean; // If true, the circle is drawn at MSL (Mean Sea Level) height
+};
+
+type ItemMapValue = [CircleInput, CircleClosestAzimuthAngleProperties];
+
+const _colorArray = new Float32Array(4 * CIRCLE_POINTS_COUNT); // Used to store the color for each circle
+
+export class CircleOnTerrainPlugin implements PluginInterface, SemiPluginInterface, ElevationMode, UpdateColor {
+    id: string;
+    globe: Globe | null = null;
+    gl: WebGLRenderingContext | null = null;
+    lineProgram: LineProgram | null = null;
+
+    bufferManagersMap: BufferManagersMap = new Map();
+    bufferOrchestrator: BufferOrchestrator = new BufferOrchestrator();
+    circleMap: Map<string, ItemMapValue> = new Map();
+
+    _cameraUniformBlock: CameraUniformBlockTotem | null = null;
+    _freed: boolean = false;
+    _circleUBOHandler: UBOHandler | null = null;
+    _opacity: number = 1;
+    _vao: WebGLVertexArrayObject | null = null;
+    _dobuild: boolean = true; // This is used to trigger the build of circles when the camera position changes.
+    _frameCounterTrigger: FrameCounterTrigger | null = null;
+    _staticDynamicStrategy: StaticDynamicStrategy | null = null;
+    _options: CircleOnTerrainPluginOptions = {
+        variativeColorsOn: false,
+        defaultColor: [0.1, 0.1, 0.1, 1], // Default color in RGBA format
+        defaultHeightFromGroundIn3D: 30.0,
+        isMSL: false
+    };
+    private _textDataPreAdaptor: ((item: Node, index: number, nodes: Node[]) => any) | undefined = undefined;
+
+
+
+    constructor(id: string, styleOptions: Partial<CircleOnTerrainPluginOptions> | null = null
+    ) {
+        this.id = id;
+        if (styleOptions) {
+            this._options = { ...this._options, ...styleOptions };
+        }
+    }
+
+
+
+    init(globe: Globe, gl: WebGL2RenderingContext): void {
+        this.globe = globe;
+        this.gl = gl;
+        // Initialize the program cache for line strip rendering.
+
+
+        this.lineProgram = LineStripProgramCache.get(globe);
+        const g2D = globe2Dcoordinates(globe);
+
+        // Initialize with a reasonable initial capacity to prevent buffer size issues
+        const initialCapacity = 100; // Start with capacity for 100 circles
+
+        this.bufferManagersMap.set("position3d", {
+            bufferManager: new BufferManager(gl, (CIRCLE_POINTS_COUNT + 1) * 3, { initialCapacity }),// plus 1 is for butting linestrips
+            adaptor: (item: any) => {
+                const { longLatArr, height = this._options.defaultHeightFromGroundIn3D, msl = this._options.isMSL } = item;
+                const result = globe3Dcoordinates(globe, longLatArr, height, msl, { paddingCount: 1, paddingValue: NaN });
+                return result;
+            }
+        });
+        this.bufferManagersMap.set("position2d", {
+            bufferManager: new BufferManager(gl, (CIRCLE_POINTS_COUNT + 1) * 2, { initialCapacity }),
+            adaptor: (item: any) => {
+                const { longLatArr } = item;
+                const result = g2D(longLatArr, { paddingCount: 1, paddingValue: NaN });
+                return result;
+            }
+        });
+
+
+        if (this._options.variativeColorsOn) {
+
+            this.bufferManagersMap.set("color", {
+                bufferManager: new BufferManager(gl, (CIRCLE_POINTS_COUNT + 1) * 4, { initialCapacity }),
+                adaptor: (item: any) => {
+                    if (item.color) {
+                        for (let i = 0; i < CIRCLE_POINTS_COUNT; i++) {
+                            _colorArray.set(item.color, i * 4);
+                        }
+                    } else {
+                        for (let i = 0; i < CIRCLE_POINTS_COUNT; i++) {
+                            _colorArray.set(this._options.defaultColor as Float32Array, i * 4);
+                        }
+                    }
+                    return _colorArray
+
+                }
+            });
+        }
+
+        this._vao = this.lineProgram.createVAO(
+            createBufferAndReadInfo(
+                this.bufferManagersMap.get("position3d")?.bufferManager.buffer as WebGLBuffer),
+            createBufferAndReadInfo(
+                this.bufferManagersMap.get("position2d")?.bufferManager.buffer as WebGLBuffer),
+            this._options.variativeColorsOn ?
+                createBufferAndReadInfo(
+                    this.bufferManagersMap.get("color")?.bufferManager.buffer as WebGLBuffer) : null,
+        );
+
+        this._circleUBOHandler = this.lineProgram.createUBO();
+        this.setDefaultColor(this._options.defaultColor);
+        this._cameraUniformBlock = CameraUniformBlockTotemCache.get(globe);
+        this._staticDynamicStrategy = new StaticDynamicStrategy(globe, ACTIVATE_DYNAMIC_STRATEGY_AT_LEVEL, () => {
+            this.__buildStaticCircles();
+        });
+        this._frameCounterTrigger = new FrameCounterTrigger(globe, 15, 1000, (globeChanges) => {
+            if (this._freed) return;
+            this._buildCircles();
+        });
+    }
+
+    increaseSpace(amount: number): void {
+        if (this._freed) {
+            console.warn("Plugin is freed, cannot increase space");
+            return;
+        }
+        if (this.globe === null) {
+            console.warn("Globe is not initialized.");
+            return;
+        }
+        if (typeof amount !== "number" || amount <= 0) {
+            console.warn("Invalid amount, must be a positive number");
+            return;
+        }
+        this.bufferOrchestrator.ensureSpace(amount, this.bufferManagersMap!);
+    }
+
+    insertBulk(circles: Array<CircleInput>) {
+        if (this._freed) return;
+        if (!this.globe || !this.gl || !this.lineProgram || !this.bufferOrchestrator ||
+            !this.bufferManagersMap || !this._vao || !this._circleUBOHandler) {
+            throw new Error("Plugin not initialized properly");
+        }
+
+        const keys: string[] = [];
+        let newItemCount = 0;
+        for (const circleInput of circles) {
+            if (circleInput.key == null || circleInput.center == null || circleInput.radius == null) {
+                console.warn(`CircleOnTerrainPlugin: Circle input is missing required properties: ${circleInput.radius} or ${circleInput.center} or ${circleInput.key}`);
+                continue;
+            }
+            if (circleInput.radius <= 0) {
+                // console.warn(`CircleOnTerrainPlugin: Circle ${circleInput.key} has non-positive radius ${circleInput.radius}. Skipping.`);
+                continue;
+            }
+
+            keys.push(circleInput.key);
+            if (!this.circleMap.has(circleInput.key)) {
+                newItemCount++;
+            }
+            const circleForAzimuthCalc: CircleClosestAzimuthAngleProperties = CircleMethods.createCircleClosestAzimuthAngleProperties(circleInput as Circle);
+            this.circleMap.set(circleInput.key, [circleInput, circleForAzimuthCalc]);
+        }
+        this.bufferOrchestrator.ensureSpace(newItemCount, this.bufferManagersMap!);
+        this._buildCircles(keys);
+        if (this._options.variativeColorsOn) {
+            this.__fillColor(keys);
+        }
+        this.globe.DrawRender();
+    }
+
+
+    updateColors(keyColorCouples: { key: string, color: Color }[], drawRender: boolean = true) {
+        if (this._freed) {
+            console.warn("Plugin is freed, cannot increase space");
+            return;
+        }
+        if (this.globe === null) {
+            console.warn("Globe is not initialized.");
+            return;
+        }
+        if (this._options.variativeColorsOn === false) {
+            console.warn("VariativeColors are not enabled");
+            return;
+        }
+        for (const { key, color } of keyColorCouples) {
+            const [circleInput] = this.circleMap.get(key) || [];
+            if (circleInput) {
+                circleInput.color = color;
+                this.__fillColor([key]);
+            } else {
+                console.warn(`Circle key ${key} not found in circleMap.`);
+            }
+        }
+        if (drawRender) {
+            this.globe.DrawRender();
+        }
+    }
+
+
+
+
+    deleteBulk(keys: Array<string>) {
+        if (this._freed) return;
+        if (!this.globe || !this.gl || !this.lineProgram || !this.bufferOrchestrator ||
+            !this.bufferManagersMap || !this._vao || !this._circleUBOHandler) {
+            throw new Error("Plugin not initialized properly");
+        }
+        this.bufferOrchestrator.deleteBulk(keys, this.bufferManagersMap);
+        for (const key of keys) {
+            if (this.circleMap.has(key)) {
+                this.circleMap.delete(key);
+            } else {
+                console.warn(`CircleOnTerrainPlugin: Circle ${key} not found in circleMap. Cannot delete.`);
+            }
+        }
+
+    }
+
+
+    setPluginOpacity(opacity: number, drawRender: boolean = false): void {
+        if (!this.globe || !this.gl) {
+            console.warn("Globe or WebGL context is not initialized.");
+            return;
+        }
+        opacityCheck(opacity);
+        this._opacity = opacity;
+
+        if (drawRender) {
+            this.globe.DrawRender();
+        }
+    }
+
+    setElevationMode(mode: "msl" | "agl"): void {
+        switch (mode) {
+            case "msl":
+                this._options.isMSL = true;
+                break;
+            case "agl":
+                this._options.isMSL = false;
+                break;
+            default:
+                throw new Error(`Unknown elevation mode: ${mode}`);
+        }
+        this._buildCircles();
+        this.globe?.DrawRender();
+    }
+
+    setDefaultColor(color: Color, drawRender: boolean = false): void {
+        if (!this.globe || !this.gl) {
+            console.warn("Globe or WebGL context is not initialized.");
+            return;
+        }
+        this._circleUBOHandler?.updateSingle("u_color", new Float32Array(color));
+        if (drawRender) {
+            this.globe.DrawRender();
+        }
+    }
+
+
+    updateCoordinates(items: Pick<CircleInput, "key" | "center" | "radius">[]): void {
+
+        if (this._freed) {
+            console.warn("CircleOnTerrainPlugin is freed, cannot update coordinates");
+            return;
+        }
+
+        if (this.globe === null) {
+            console.warn("Globe is not initialized, cannot update coordinates");
+            return;
+        }
+        const updateKeys: string[] = [];
+        for (const item of items) {
+            const { key, center, radius } = item;
+            const [circleInput] = this.circleMap.get(key) || [];
+            if (circleInput) {
+                circleInput.center = center;
+                circleInput.radius = radius;
+                updateKeys.push(key);
+            } else {
+                console.warn(`Circle key ${key} not found in circleMap.`);
+                continue;
+            }
+        }
+        this._buildCircles(updateKeys);
+        this.globe!.DrawRender();
+    }
+
+    // IMPLICIT METHODS
+
+    __fillColor(subSetIDs: Array<string>) {
+        if (!this._options.variativeColorsOn) return;
+        const wrapper: [CircleInput] = [null!]
+        for (const key of subSetIDs) {
+            const [circleInput,] = this.circleMap.get(key) || [];
+            if (circleInput) {
+                wrapper[0] = circleInput;
+                this.bufferOrchestrator.insertBulk(
+                    wrapper,
+                    this.bufferManagersMap,
+                    ["color"]
+                )
+            }
+        }
+    }
+
+    _buildCircles(subSetIDs: Array<string> | null = null) {
+        // @ts-ignore
+        this._staticDynamicStrategy?.updateState();
+        const state = this._staticDynamicStrategy?.getState();
+        if (state === StaticDynamicState.DYNAMIC) {
+            this.__buildDynamicCircles(subSetIDs);
+        } else if (subSetIDs || state === StaticDynamicState.TO_STATIC) {
+            this.__buildStaticCircles(subSetIDs);
+        }
+    }
+
+
+    __buildDynamicCircles(subSetIDs: Array<string> | null = null) { // TODO: Modify it to build set of dynamic circles
+        const {
+            globe, gl, _cameraUniformBlock, lineProgram, bufferOrchestrator, bufferManagersMap, circleMap
+        } = this;
+        if (!globe || !gl || !_cameraUniformBlock || !lineProgram ||
+            !bufferOrchestrator || !bufferManagersMap || !circleMap
+        ) throw new Error("Plugin not initialized properly");
+
+        // unoptimized.. resets all circles.
+        // bufferOrchestrator.resetWithCapacity(bufferManagersMap, circleMap.size);
+        // Prepare the data for the buffers
+        const data: [{ key: string, longLatArr: Float64Array | number[], height: Meter | null, msl: boolean | null }] = [{
+            key: "",
+            longLatArr: [],
+            height: null,
+            msl: null
+        }];
+
+
+        const lookAtPosition = _cameraUniformBlock.getLookAtVector();
+        const cameraPosition = _cameraUniformBlock.getNormalizedCameraVector();
+        vec3.divideScalar(cameraPosition, cameraPosition, WORLD_RADIUS_3D);
+        vec3.add(cameraPosition, cameraPosition, lookAtPosition);
+        vec3.normalize(cameraPosition, cameraPosition);
+
+
+        const currentLOD = globe.api_GetCurrentLODWithDecimal();
+        const circlePointsLongLat = new Float64Array((CIRCLE_POINTS_COUNT) * 2);
+
+        let keys;
+        if (!subSetIDs || subSetIDs.length === 0) {
+            keys = Array.from(this.circleMap.keys());
+            // bufferOrchestrator.resetWithCapacity(bufferManagersMap, circleMap.size);
+        } else {
+            keys = subSetIDs;
+        }
+
+        for (const key of keys) {
+            const [{ radius, center, height = null, msl = null }, circleForAzimuthCalc] = this.circleMap.get(key) as ItemMapValue;
+
+            const closestAzimuthAngle = CircleMethods.closestAzimuthAngle(
+                circleForAzimuthCalc, cameraPosition)
+
+            const stregthLevel = defineStregthLevel(currentLOD, radius);
+            if (typeof stregthLevel !== "number") {
+                console.warn(`CircleOnTerrainPlugin: Circle ${key} has invalid strength level for current LOD ${currentLOD}. Skipping., radius: ${radius}, stregthLevel: ${stregthLevel}`);
+                continue;
+            }
+            if (stregthLevel < 0) {
+                console.warn(`CircleOnTerrainPlugin: Circle ${key} has too small radius for current LOD ${currentLOD}. Skipping., radius: ${radius}, stregthLevel: ${stregthLevel}`);
+                continue;
+            }
+
+            const templateAngles = AnglesStash[stregthLevel];
+
+            CircleCDF.globeFindPointByPolarHalfCircle(
+                circlePointsLongLat,
+                globe,
+                center[0],
+                center[1],
+                radius,
+                closestAzimuthAngle,
+                templateAngles
+            );
+            data[0].key = key;
+            data[0].longLatArr = circlePointsLongLat;
+            data[0].height = height;
+            data[0].msl = msl;
+
+            // Add to buffer orchestrator
+            this.bufferOrchestrator.insertBulk(data, bufferManagersMap, [
+                this.globe?.api_GetCurrentGeometry() === 0 ? "position3d" : "position2d",
+            ]);
+        }
+    }
+
+
+
+    // this will be used to build static circles, which are not affected by camera position or LOD.
+    // LOD < 8 or something
+    __buildStaticCircles(subSetIDs: Array<string> | null = null) { // TODO: Modify it to build set of static circles
+        const { globe, gl, _cameraUniformBlock, lineProgram, bufferOrchestrator, bufferManagersMap, circleMap } = this;
+        if (!globe || !gl || !_cameraUniformBlock || !lineProgram ||
+            !bufferOrchestrator || !bufferManagersMap || !circleMap
+        ) throw new Error("Plugin not initialized properly");
+
+        const datas = []
+        // ensure buffer orchestrotrator have enough capacity
+
+        // all circles are build with even sampling, AttractionLevel = 0
+        const templateAngles = AnglesStash[0];
+        const zeroRotation = 0;
+        let keys: Array<string>;
+        if (!subSetIDs || subSetIDs.length === 0) {
+            keys = Array.from(this.circleMap.keys());
+            // bufferOrchestrator.resetWithCapacity(bufferManagersMap, circleMap.size);
+        } else {
+            keys = subSetIDs
+        }
+
+        for (let key of keys) {
+            if (!this.circleMap.has(key)) {
+                console.warn(`CircleOnTerrainPlugin: Circle ${key} not found in circleMap.`);
+                continue;
+            }
+            const [{ radius, center, height = null, color = null, msl = undefined },] = this.circleMap.get(key) as ItemMapValue;
+            const circlePointsLongLat = new Float64Array((CIRCLE_POINTS_COUNT) * 2);
+            CircleCDF.globeFindPointByPolarHalfCircle(
+                circlePointsLongLat,
+                globe,
+                center[0],
+                center[1],
+                radius,
+                zeroRotation,
+                templateAngles
+            );
+
+            datas.push({
+                key,
+                longLatArr: circlePointsLongLat,
+                height,
+                color: color || this._options.defaultColor,
+                msl
+            });
+        }
+        this.bufferOrchestrator.insertBulk(datas, bufferManagersMap,
+            [this.globe?.api_GetCurrentGeometry() === 0 ? "position3d" : "position2d"]
+        );
+    }
+
+
+
+    // GLOBE API INTERFACE
+    draw3D() {
+        const { _freed, globe, gl, lineProgram, bufferOrchestrator, bufferManagersMap, _vao, _circleUBOHandler } = this;
+        if (_freed || !globe || !gl || !lineProgram || !bufferOrchestrator ||
+            !bufferManagersMap || !_vao || !_circleUBOHandler) {
+            return;
+        }
+
+        // if (globe.api_IsScreenMoving())
+        this._frameCounterTrigger?.trigger();
+        // this._buildCircles();
+
+
+        const drawOptions: DrawRangeIndexParams = {
+            drawRange: {
+                first: 0,
+                count: bufferOrchestrator.length * (CIRCLE_POINTS_COUNT + 1), // plus 1 is for cutting linestrips
+
+            },
+        }
+
+        gl.disable(gl.DEPTH_TEST);
+
+        lineProgram.draw(
+            _vao,
+            drawOptions,
+            this._opacity,
+            _circleUBOHandler
+        )
+        gl.enable(gl.DEPTH_TEST);
+    }
+
+
+
+    free() {
+        if (this._freed) return;
+        this._freed = true;
+        if (this.lineProgram) {
+            LineStripProgramCache.release(this.lineProgram);
+            this.lineProgram = null;
+        }
+        this.circleMap.clear();
+        this.bufferManagersMap.forEach(({ bufferManager }) => {
+            bufferManager.free();
+        });
+        this.bufferManagersMap.clear();
+        CameraUniformBlockTotemCache.release(this.globe as Globe);
+
+
+    }
+}
+