DOCSEARCHbyAlgolia
Submit Docs

OpenGlobus Documentation

repository·master·Indexed 21 days ago

https://github.com/openglobus/openglobus

An open-source TypeScript/JavaScript library using WebGL to display interactive 3D maps and planets. It supports map tiles, imagery, vector data, markers, and 3D objects at scales from planetary to microscopic. The library includes tools for frustum culling, Julian date conversions, point cloud rendering, and a dedicated React integration package (@openglobus/openglobus-react).

Tokens
12.5K
Snippets
55
Records
70
Agent score
76%

What's inside OpenGlobus

  3. Follow OpenGlobus documentation and PR conventions

    master

    When contributing to the project, follow these conventions to ensure high code quality and maintainable documentation:

    • Focus Changes: Keep changes focused on a single concern per Pull Request. Do not mix functional changes with unrelated formatting-only changes.
    • Update Documentation: Always update documentation when changing public behavior or APIs.
    • JSDoc Requirements: Document all new public features using JSDoc-style comments.
    • Verify Docs: For feature Pull Requests, verify that the documentation builds correctly by running npm run docs locally.

  4. Initialize an OpenGlobus project with create-openglobus

    master

    For a fast start, use the create-openglobus template. This scaffolding tool supports JavaScript, TypeScript, React, and other environments. Run the following command to start the interactive setup:

    npx create-openglobus

  7. Run recommended checks before contributing

    master

    Before opening a Pull Request, run the following commands locally to ensure your changes meet the project's linting, formatting, testing, and documentation standards:

    npm run lint
npm run format
npm run test
npm run docs
npm run build

  8. Perform in-place vector operations with Vec4

    master

    Several Vec4 methods perform operations in-place (mutating the existing instance) and return this to allow chaining. Use these when performance is a priority and you do not need to preserve the original vector.

    • set(x, y, z, w): Updates all components.
    • copy(v): Copies values from another Vec4.
    • addA(v): Adds vector v to the current instance.
    • subA(v): Subtracts vector v from the current instance.
    • scale(scale): Multiplies all components by a scalar.
    • affinity(): Normalizes the vector so w is 1.0.
    const v = vec4(1, 1, 1, 1);
v.addA(vec4(2, 2, 2, 2)).scale(0.5).set(0, 0, 0, 1);

  9. Initialize a Frustum

    master

    The Frustum class represents the camera's view volume and provides methods for frustum culling. You can initialize it using an options object of type IFrustumParams.

    Options:

    • cameraFrustumIndex (number, optional): Index of the camera frustum. Defaults to -1.
    • fov (number, optional): Vertical field of view angle in degrees. Defaults to 30.0.
    • aspect (number, optional): Viewport aspect ratio (width / height). Defaults to 1.0.
    • near (number, optional): Near clipping plane distance. Defaults to 1.0.
    • far (number, optional): Far clipping plane distance. Defaults to 1000.0.
    • isOrthographic (boolean, optional): If true, uses orthographic projection. Defaults to false.
    • focusDistance (number, optional): Reference distance used to compute orthographic frustum size. Defaults to 10.
    • reverseDepth (boolean, optional): Enables reverse-Z infinite perspective projection.
    • depthZeroToOne (boolean, optional): Uses [0, 1] NDC depth range for reverse-Z projection.
    import { Frustum } from './src/camera/Frustum';

const frustum = new Frustum({
    fov: 45,
    aspect: 16 / 9,
    near: 0.1,
    far: 1000,
    isOrthographic: false
});

  10. Initialize RendererEvents

    master

    To handle input and rendering lifecycle events, use the createRendererEvents function, passing in your Renderer instance. This returns a RendererEvents object that allows you to listen for mouse, touch, keyboard, and rendering pass events.

    import { createRendererEvents } from "@openglobus/og";

const events = createRendererEvents(renderer);
events.on("lclick", (mouseState) => {
    console.log("Left click at:", mouseState.pos);
});

  11. Perform Frustum Culling Tests

    master

    The Frustum class provides several methods to check if geometric objects are within the view volume:

    • containsPoint(point: Vec3): Returns true if a Cartesian point is inside the frustum.
    • containsSphere(sphere: Sphere): Returns true if a bounding sphere is inside the frustum.
    • containsSphere2(center: Vec3, radius: number): Returns true if a sphere defined by a center and radius is inside the frustum.
    • containsBox(box: Box): Returns true if a bounding box intersects or is inside the frustum.

    Specialized Sphere Tests:

    • containsSphereBottomExc(sphere: Sphere): Checks if a sphere is inside the frustum but ignores the bottom plane (useful for specific culling optimizations).
    • containsSphereButtom(sphere: Sphere): Checks only if the sphere is not clipped by the bottom plane.
    // Test a point
if (frustum.containsPoint(new Vec3(0, 0, -5))) { /* ... */ }

// Test a sphere
if (frustum.containsSphere(mySphere)) { /* ... */ }

// Test a box
if (frustum.containsBox(myBox)) { /* ... */ }

  12. Configure Frustum Projection Matrices

    master

    Use setProjectionMatrix to update the camera's projection parameters. This method recalculates the projection matrix and its inverse.

    Parameters:

    • viewAngle: Vertical field of view in degrees.
    • aspect: Viewport aspect ratio.
    • near: Near clipping plane distance.
    • far: Far clipping plane distance.
    • isOrthographic: Whether to use orthographic projection.
    • focusDistance: Reference distance for orthographic bounds.
    • reverseDepth: Whether to use reverse-Z infinite perspective.
    • depthZeroToOne: Whether to use [0, 1] NDC depth range.
    frustum.setProjectionMatrix(45, 1.77, 0.1, 1000, false, 10, false, false);