@xbibzlibrary/3dcanvas

v1.0.3

Published

4 months ago

Advanced 3D Globe Rendering Library with Customizable Text Overlay

0High
0Medium
0Low

xbibzbackup

3d globe canvas webgl visualization earth map interactive

@xbibzlibrary/3dcanvas

📋 Table of Contents

✨ Features

🎪 Additional Features

🎨 Custom Shaders - Full GLSL shader support for advanced effects
🖼️ Texture Loading - Async texture loading with caching and fallback
🔧 Config Manager - Dynamic configuration with validation and watchers
🐛 Error Handling - Advanced error tracking and debugging tools
📝 Logging System - Multi-level logging with history and export
🎮 Interactive Controls - Mouse and touch support for rotation, zoom, and pan
📱 Responsive - Auto-resize and mobile-friendly
🌐 No Dependencies - Pure JavaScript, no external libraries required

🎯 Why Choose This Library?

💪 Powerful & Complete

Unlike other 3D libraries, @xbibzlibrary/3dcanvas comes with everything you need out of the box:

✅ Complete rendering pipeline
✅ Built-in animation system
✅ Particle effects
✅ Text rendering
✅ Performance monitoring
✅ Error handling
✅ Event management

🚀 High Performance

Optimized WebGL rendering
Efficient buffer management
Adaptive quality system
Frame rate limiting
Memory usage tracking

🎨 Developer Friendly

Clean, modern ES6+ code
Comprehensive documentation
TypeScript-ready structure
Extensive examples
Active support

📦 Installation

Via NPM

npm install @xbibzlibrary/3dcanvas

Via Yarn

yarn add @xbibzlibrary/3dcanvas

Via CDN (jsDelivr)

<script type="module">
  import { Globe3D, TextRenderer } from 'https://cdn.jsdelivr.net/npm/@xbibzlibrary/[email protected]/dist/xbibzlibrary-3dcanvas.min.js';
</script>

Direct Download

Download the latest release from GitHub Releases

🚀 Quick Start

1️⃣ Basic Setup (30 seconds!)

<!DOCTYPE html>
<html>
<head>
    <title>My Globe</title>
    <style>
        body { margin: 0; overflow: hidden; }
        #container { width: 100vw; height: 100vh; }
    </style>
</head>
<body>
    <div id="container"></div>
    
    <script type="module">
        import { Globe3D } from './src/Globe3D.js';
        
        // Create globe
        const globe = new Globe3D(
            document.getElementById('container'),
            {
                radius: 1.0,
                autoRotate: true,
                atmosphere: true
            }
        );
        
        // Wait for initialization
        globe.on('initialized', () => {
            console.log('Globe ready! 🌍');
        });
    </script>
</body>
</html>

2️⃣ Add Markers

// Add a marker at specific coordinates
const markerId = globe.addMarker(
    40.7128,  // latitude (New York)
    -74.0060, // longitude
    {
        color: [1.0, 0.5, 0.2],
        size: 0.02
    }
);

3️⃣ Add Text Labels

import { TextRenderer } from './src/TextRenderer.js';

const textRenderer = new TextRenderer(globe, {
    fontSize: 14,
    color: '#ffffff'
});

textRenderer.addLabel(
    'nyc_label',
    'New York City',
    40.7128,
    -74.0060
);

4️⃣ Create Particle Effects

import { Vector3, Color } from './src/Globe3D.js';

const emitterId = globe.addParticleEmitter({
    position: new Vector3(0, 1, 0),
    rate: 50,
    lifetime: 3,
    size: { min: 0.1, max: 0.3 },
    color: new Color(1, 0.5, 0.2),
    velocity: new Vector3(0, 1, 0),
    spread: 0.5
});

📖 Documentation

🏗️ How It Works

Architecture Overview

┌─────────────────────────────────────────┐
│         Globe3D (Main Class)            │
│  ┌─────────────────────────────────┐   │
│  │   WebGL Rendering Pipeline      │   │
│  └─────────────────────────────────┘   │
│                                         │
│  ┌──────────┐  ┌──────────┐           │
│  │ Shaders  │  │ Textures │           │
│  └──────────┘  └──────────┘           │
└─────────────────────────────────────────┘
         │              │
         ▼              ▼
┌─────────────┐  ┌─────────────┐
│  Particles  │  │    Text     │
│   System    │  │  Renderer   │
└─────────────┘  └─────────────┘
         │              │
         ▼              ▼
┌──────────────────────────────┐
│     Animation Engine         │
│  ┌────────┐  ┌────────┐     │
│  │ Events │  │ Config │     │
│  └────────┘  └────────┘     │
└──────────────────────────────┘
         │
         ▼
┌──────────────────────────────┐
│  Performance & Error System  │
└──────────────────────────────┘

Rendering Pipeline

Initialization Phase
- Create WebGL context
- Compile shaders
- Load textures
- Setup buffers
Update Phase
- Update animations
- Update particles
- Handle interactions
- Process events
Render Phase
- Clear buffers
- Render globe
- Render atmosphere
- Render particles
- Update text positions
Monitoring Phase
- Track FPS
- Monitor memory
- Log performance

🎮 Usage Guide

Basic Configuration

const globe = new Globe3D(container, {
    // Rendering options
    antialias: true,
    alpha: true,
    
    // Globe settings
    radius: 1.0,
    segments: 64,
    textureUrl: '/path/to/texture.jpg',
    wireframe: false,
    
    // Atmosphere
    atmosphere: true,
    atmosphereColor: [0.3, 0.5, 1.0],
    atmosphereOpacity: 0.3,
    
    // Lighting
    ambientLight: [0.3, 0.3, 0.3],
    diffuseLight: [0.7, 0.7, 0.7],
    lightDirection: [1.0, 1.0, 1.0],
    
    // Animation
    autoRotate: true,
    rotationSpeed: 0.001,
    
    // Interaction
    enableZoom: true,
    enableRotate: true,
    enablePan: true,
    minDistance: 0.5,
    maxDistance: 5.0,
    
    // Performance
    maxFPS: 60,
    adaptiveQuality: true
});

Event Handling

// Listen to globe events
globe.on('initialized', (data) => {
    console.log('Globe initialized!', data);
});

globe.on('rotate', (data) => {
    console.log('Globe rotated', data.deltaX, data.deltaY);
});

globe.on('zoom', (data) => {
    console.log('Zoom changed', data.distance);
});

globe.on('markerAdded', (data) => {
    console.log('New marker:', data);
});

Working with Animations

// Create custom animation
const animId = globe.createAnimation(
    camera,              // target object
    { x: 5, y: 2, z: 3 }, // end values
    {
        duration: 2000,  // milliseconds
        easing: 'easeInOutQuad',
        loop: false,
        yoyo: false,
        onStart: () => console.log('Animation started'),
        onUpdate: (progress) => console.log('Progress:', progress),
        onComplete: () => console.log('Animation completed')
    }
);

🎨 Examples

Example 1: World Map with Cities

const cities = [
    { name: 'Tokyo', lat: 35.6762, lng: 139.6503, pop: 37400000 },
    { name: 'Delhi', lat: 28.7041, lng: 77.1025, pop: 30290000 },
    { name: 'Shanghai', lat: 31.2304, lng: 121.4737, pop: 27058000 },
    { name: 'São Paulo', lat: -23.5505, lng: -46.6333, pop: 22043000 },
    { name: 'Mexico City', lat: 19.4326, lng: -99.1332, pop: 21782000 }
];

cities.forEach(city => {
    // Add marker
    globe.addMarker(city.lat, city.lng, {
        color: [1, 0.5, 0],
        size: Math.log(city.pop) * 0.002
    });
    
    // Add label
    textRenderer.addLabel(
        `city_${city.name}`,
        `${city.name}\n${(city.pop / 1000000).toFixed(1)}M`,
        city.lat,
        city.lng,
        {
            fontSize: 12,
            backgroundColor: 'rgba(0, 0, 0, 0.8)'
        }
    );
});

Example 2: Animated Flight Paths

function createFlightPath(from, to) {
    const startPos = globe.latLongToVector3(from.lat, from.lng);
    const endPos = globe.latLongToVector3(to.lat, to.lng);
    
    // Create particle trail
    const emitter = globe.addParticleEmitter({
        position: startPos,
        rate: 20,
        lifetime: 2,
        velocity: endPos.clone().subtract(startPos).normalize(),
        color: new Color(0.2, 0.8, 1.0)
    });
    
    // Animate emitter along path
    globe.createAnimation(
        emitter,
        { position: endPos },
        {
            duration: 5000,
            easing: 'easeInOutQuad'
        }
    );
}

Example 3: Interactive Dashboard

// Create interactive globe dashboard
class GlobeDashboard {
    constructor(container) {
        this.globe = new Globe3D(container, {
            autoRotate: false,
            atmosphere: true
        });
        
        this.textRenderer = new TextRenderer(this.globe);
        this.selectedCountry = null;
        
        this.setupInteractions();
    }
    
    setupInteractions() {
        // Handle text clicks
        this.textRenderer.on('textClick', (data) => {
            this.showCountryInfo(data.textElement.text);
        });
        
        // Handle globe clicks
        this.globe.canvas.addEventListener('click', (e) => {
            const worldPos = this.globe.screenToWorld(e.clientX, e.clientY);
            this.addInteractiveMarker(worldPos);
        });
    }
    
    showCountryInfo(countryName) {
        console.log(`Showing info for: ${countryName}`);
        // Display country statistics, charts, etc.
    }
    
    addInteractiveMarker(position) {
        const markerId = this.globe.addMarker(
            position.latitude,
            position.longitude,
            { color: [1, 0, 0], size: 0.02 }
        );
        
        // Add popup
        this.textRenderer.addText(
            `marker_${markerId}`,
            'New Marker',
            position,
            {
                fontSize: 14,
                backgroundColor: 'rgba(255, 0, 0, 0.8)'
            }
        );
    }
}

// Initialize dashboard
const dashboard = new GlobeDashboard(document.getElementById('container'));

⚙️ Configuration

Globe Configuration Reference

| Option | Type | Default | Description | |--------|------|---------|-------------| | radius | number | 1.0 | Globe radius | | segments | number | 64 | Number of geometry segments | | textureUrl | string | null | URL to texture image | | autoRotate | boolean | true | Enable auto-rotation | | rotationSpeed | number | 0.001 | Rotation speed | | atmosphere | boolean | true | Enable atmosphere effect | | enableZoom | boolean | true | Enable zoom interaction | | minDistance | number | 0.5 | Minimum camera distance | | maxDistance | number | 5.0 | Maximum camera distance |

Text Renderer Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | fontFamily | string | 'Arial' | Font family | | fontSize | number | 14 | Font size in pixels | | color | string | '#ffffff' | Text color | | backgroundColor | string | 'rgba(0,0,0,0.7)' | Background color | | padding | number | 8 | Padding in pixels | | borderRadius | number | 4 | Border radius | | maxWidth | number | 200 | Maximum width |

📊 Performance

Benchmarks

| Metric | Value | Notes | |--------|-------|-------| | FPS (60Hz display) | 60 FPS | Solid 60fps with 100+ markers | | FPS (144Hz display) | 144 FPS | High refresh rate support | | Memory Usage | ~50MB | Base memory footprint | | Startup Time | <500ms | Fast initialization | | Particle Count | 10,000+ | Simultaneous particles | | Text Labels | 500+ | Smooth rendering |

Optimization Tips

// 1. Use adaptive quality
globe.setConfig('adaptiveQuality', true);

// 2. Limit FPS for better battery life
globe.setConfig('maxFPS', 30);

// 3. Monitor performance
setInterval(() => {
    const report = globe.getPerformanceReport();
    console.log('FPS:', report.summary.fps.current);
}, 1000);

// 4. Dispose unused resources
textRenderer.removeText('unused_label_id');
globe.removeParticleEmitter('old_emitter_id');

🤝 Contributing

We welcome contributions! See our Contributing Guide for details.

# Fork and clone the repository
git clone https://github.com/xbibzofficial/3dcanvas.git

# Install dependencies
npm install

# Run development server
npm run dev

# Build for production
npm run build

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@xbibzlibrary/3dcanvas

📋 Table of Contents

✨ Features

🎪 Additional Features

🎯 Why Choose This Library?

💪 Powerful & Complete

🚀 High Performance

🎨 Developer Friendly

📦 Installation

Via NPM

Via Yarn

Via CDN (jsDelivr)

Direct Download

🚀 Quick Start

1️⃣ Basic Setup (30 seconds!)

2️⃣ Add Markers

3️⃣ Add Text Labels

4️⃣ Create Particle Effects

📖 Documentation

🏗️ How It Works

Architecture Overview

Rendering Pipeline

🎮 Usage Guide

Basic Configuration

Event Handling

Working with Animations

🎨 Examples

Example 1: World Map with Cities

Example 2: Animated Flight Paths

Example 3: Interactive Dashboard

⚙️ Configuration

Globe Configuration Reference

Text Renderer Configuration

📊 Performance

Benchmarks

Optimization Tips

🤝 Contributing

📄 License

💖 Support

Love this library? Support the development! ❤️

Connect with us 🌐