gralobe 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,325 @@
+/**
+ * Built-in statistics available out of the box
+ */
+export declare const BUILT_IN_STATISTICS: Record<string, StatisticDefinition>;
+
+/**
+ * Country data with a value for visualization
+ * Uses ISO 3166-1 numeric codes for country identification
+ */
+export declare interface CountryData {
+    /** ISO 3166-1 numeric code (e.g., "840" for USA, "156" for China) */
+    id: string;
+    /** The value to visualize */
+    value: number;
+    /** Optional: ISO 3166-1 alpha-2 code (e.g., "US", "CN") */
+    code?: string;
+    /** Optional: Country name for display */
+    name?: string;
+}
+
+/**
+ * Real World Statistics Data
+ * Sources: World Bank Open Data, UN Data, WHO (2022-2023 estimates)
+ * Country codes follow ISO 3166-1 numeric standard
+ */
+declare interface CountryStatistics {
+    id: string;
+    code: string;
+    name: string;
+    population: number;
+    gdpPerCapita: number;
+    co2Emissions: number;
+    lifeExpectancy: number;
+    humanDevIndex: number;
+    internetUsers: number;
+    renewableEnergy: number;
+    urbanPopulation: number;
+    healthExpenditure: number;
+    educationExpenditure: number;
+    forestArea: number;
+    accessElectricity: number;
+}
+
+/**
+ * Visual effects configuration
+ */
+declare interface EffectsConfig {
+    /** Show cloud layer */
+    clouds?: boolean;
+    /** Cloud animation speed (0.1-3) */
+    cloudSpeed?: number;
+    /** Cloud layer opacity (0-1) */
+    cloudOpacity?: number;
+    /** Atmosphere glow intensity (0-1) */
+    atmosphereIntensity?: number;
+    /** Show aurora effect */
+    aurora?: boolean;
+    /** Show city lights on dark side */
+    cityLights?: boolean;
+    /** Ocean specular reflection */
+    oceanSpecular?: boolean;
+    /** Show lat/lon grid lines */
+    gridLines?: boolean;
+    /** Grid line opacity (0-1) */
+    gridOpacity?: number;
+    /** Hologram visual mode */
+    hologramMode?: boolean;
+    /** Vintage/sepia mode */
+    vintageMode?: boolean;
+    /** Thermal imaging mode */
+    thermalMode?: boolean;
+    /** Blueprint wireframe mode */
+    blueprintMode?: boolean;
+    /** Pulsing glow effect */
+    glowPulse?: boolean;
+    /** Star twinkling animation */
+    starTwinkle?: boolean;
+}
+
+/**
+ * Export options for screenshots, GIFs, and videos
+ */
+declare interface ExportOptions {
+    /** Output width in pixels */
+    width?: number;
+    /** Output height in pixels */
+    height?: number;
+    /** Animation duration in seconds (for GIF/video) */
+    duration?: number;
+    /** Frames per second (for GIF/video) */
+    fps?: number;
+    /** Output filename */
+    filename?: string;
+}
+
+/**
+ * GlobeViz - Interactive 3D Globe Visualization
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const globe = new GlobeViz('#container');
+ *
+ * // With configuration
+ * const globe = new GlobeViz('#container', {
+ *   texture: 'satellite',
+ *   labels: 'all',
+ *   statistic: 'lifeExpectancy',
+ *   autoRotate: true,
+ * });
+ *
+ * // Control programmatically
+ * globe.toFlat();
+ * globe.setStatistic('gdpPerCapita');
+ * ```
+ */
+export declare class GlobeViz implements GlobeVizAPI {
+    private container;
+    private config;
+    private scene;
+    private camera;
+    private renderer;
+    private controls;
+    private globe;
+    private material;
+    private atmosphere;
+    private stars;
+    private gui;
+    private choropleth;
+    private legend;
+    private exporter;
+    private countryLabels;
+    private textureLoader;
+    private dataTexture;
+    private morph;
+    private currentStatistic;
+    private animationId;
+    private isDestroyed;
+    /**
+     * Create a new GlobeViz instance
+     * @param container CSS selector or HTMLElement
+     * @param config Configuration options
+     */
+    constructor(container: string | HTMLElement, config?: GlobeVizConfig);
+    private init;
+    private createGlobe;
+    private createAtmosphere;
+    private createStars;
+    private createGUI;
+    private handleResize;
+    private animate;
+    toGlobe(): void;
+    toFlat(): void;
+    setMorph(value: number): void;
+    getMorph(): number;
+    setStatistic(id: string | StatisticData): void;
+    setLabels(style: LabelStyle): void;
+    setTexture(preset: TexturePreset): Promise<void>;
+    setAutoRotate(enabled: boolean): void;
+    screenshot(options?: ExportOptions): void;
+    recordGif(options?: ExportOptions): Promise<void>;
+    recordVideo(options?: ExportOptions): Promise<void>;
+    setEffects(effects: Partial<EffectsConfig>): void;
+    resize(width: number, height: number): void;
+    destroy(): void;
+}
+
+/**
+ * Public API for controlling the globe
+ */
+export declare interface GlobeVizAPI {
+    /** Animate to globe view */
+    toGlobe(): void;
+    /** Animate to flat map view */
+    toFlat(): void;
+    /** Set morph value directly (0 = flat, 1 = globe) */
+    setMorph(value: number): void;
+    /** Get current morph value */
+    getMorph(): number;
+    /** Change the displayed statistic */
+    setStatistic(id: string | StatisticData): void;
+    /** Change label style */
+    setLabels(style: LabelStyle): void;
+    /** Change texture */
+    setTexture(preset: TexturePreset): void;
+    /** Enable/disable auto-rotation */
+    setAutoRotate(enabled: boolean): void;
+    /** Take a screenshot */
+    screenshot(options?: ExportOptions): void;
+    /** Record a GIF animation */
+    recordGif(options?: ExportOptions): Promise<void>;
+    /** Record a video */
+    recordVideo(options?: ExportOptions): Promise<void>;
+    /** Update effects configuration */
+    setEffects(effects: Partial<EffectsConfig>): void;
+    /** Resize the visualization */
+    resize(width: number, height: number): void;
+    /** Destroy the instance and clean up */
+    destroy(): void;
+}
+
+/**
+ * Configuration options for GlobeViz
+ */
+export declare interface GlobeVizConfig {
+    /**
+     * Earth texture preset
+     * @default 'satellite' (NASA Blue Marble)
+     */
+    texture?: TexturePreset;
+    /**
+     * Country label display style
+     * @default 'all'
+     */
+    labels?: LabelStyle;
+    /**
+     * Initial statistic to display
+     * Can be a built-in statistic ID or a custom StatisticData object
+     * @default 'lifeExpectancy'
+     */
+    statistic?: string | StatisticData;
+    /**
+     * Custom statistics data (country values)
+     * If not provided, uses built-in world statistics
+     */
+    data?: CountryData[];
+    /**
+     * Enable auto-rotation
+     * @default false
+     */
+    autoRotate?: boolean;
+    /**
+     * Initial view: 'globe' or 'flat'
+     * @default 'globe'
+     */
+    initialView?: 'globe' | 'flat';
+    /**
+     * Show control panel (lil-gui)
+     * @default true
+     */
+    showControls?: boolean;
+    /**
+     * Show legend
+     * @default true
+     */
+    showLegend?: boolean;
+    /**
+     * Visual effects configuration
+     */
+    effects?: EffectsConfig;
+    /**
+     * Enable 3D height extrusion based on data values
+     * @default false
+     */
+    extrudeHeight?: boolean;
+    /**
+     * Width of the container (defaults to container's width)
+     */
+    width?: number;
+    /**
+     * Height of the container (defaults to container's height)
+     */
+    height?: number;
+    /**
+     * Callback when a country is clicked
+     */
+    onCountryClick?: (countryId: string, countryName: string, value?: number) => void;
+    /**
+     * Callback when view changes between flat and globe
+     */
+    onViewChange?: (view: 'globe' | 'flat', morph: number) => void;
+}
+
+export declare type LabelStyle = 'none' | 'major' | 'all' | 'capitals' | 'minimal';
+
+/**
+ * Complete statistic data ready for visualization
+ */
+export declare interface StatisticData {
+    /** The statistic definition */
+    definition: StatisticDefinition;
+    /** Country values keyed by ISO 3166-1 numeric code */
+    values: Map<string, number> | Record<string, number>;
+}
+
+/**
+ * Definition of a statistic to visualize
+ */
+export declare interface StatisticDefinition {
+    /** Unique identifier */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Unit of measurement (e.g., "%", "years", "$") */
+    unit: string;
+    /** Description for legend/tooltip */
+    description: string;
+    /**
+     * Color scale as [low, mid, high] hex colors
+     * @example ['#fee5d9', '#fcae91', '#cb181d']
+     */
+    colorScale: [string, string, string];
+    /**
+     * Value domain [min, max] for color mapping
+     * @example [0, 100] for percentages
+     */
+    domain: [number, number];
+    /**
+     * Format function for displaying values
+     * @example (v) => `${v.toFixed(1)}%`
+     */
+    format: (value: number) => string;
+}
+
+/**
+ * Type definitions for GlobeViz
+ */
+/**
+ * Available texture presets for the globe
+ */
+export declare type TexturePreset = 'satellite' | 'natural' | 'dark' | 'light' | 'night' | 'topographic';
+
+export declare const WORLD_STATISTICS: CountryStatistics[];
+
+export { }

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "gralobe",
+  "version": "1.0.0",
+  "description": "Interactive 3D globe visualization with statistics, smooth flat map ↔ globe transitions, and country labels",
+  "type": "module",
+  "main": "./dist/gralobe.umd.cjs",
+  "module": "./dist/gralobe.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/gralobe.js",
+      "require": "./dist/gralobe.umd.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "globe",
+    "3d",
+    "visualization",
+    "map",
+    "statistics",
+    "three.js",
+    "webgl",
+    "choropleth",
+    "earth",
+    "world",
+    "geography",
+    "data-visualization"
+  ],
+  "author": "BATIKAN BORA ORMANCI <batikanor@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/batikanor/gralobe"
+  },
+  "homepage": "https://github.com/batikanor/gralobe#readme",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "build:lib": "tsc && vite build --mode lib",
+    "preview": "vite preview",
+    "prepublishOnly": "npm run build:lib"
+  },
+  "peerDependencies": {
+    "three": ">=0.150.0"
+  },
+  "devDependencies": {
+    "@types/topojson-client": "^3.1.5",
+    "@types/topojson-specification": "^1.0.5",
+    "typescript": "~5.9.3",
+    "vite": "^7.2.4",
+    "vite-plugin-dts": "^4.5.4"
+  },
+  "dependencies": {
+    "@types/three": "^0.181.0",
+    "gifenc": "^1.0.3",
+    "gsap": "^3.13.0",
+    "lil-gui": "^0.21.0",
+    "three": ">=0.150.0",
+    "topojson-client": "^3.1.0",
+    "world-atlas": "^2.0.2"
+  }
+}