Documentation

Overview

Content - MiniGlobe is a Joomla content plugin that embeds interactive 3D globes into your articles using a simple {miniglobe} tag. Built with pure WebGL2 (no external dependencies), it renders lightweight, highly optimized globes with a canvas element inside a <div> with the plg_content_miniglobe class. Perfect for adding visually striking, data-driven infographics, MiniGlobe supports custom textures, intelligent dynamic markers, procedural land/ocean coloring, optional atmospheric effects, and responsive sizing to fit any container.

Version 5.2+ represents a complete rewrite: the core JavaScript is just 52KB (92% smaller than the previous Three.js-based version), with no external dependencies.

Installation

1. Download Content - MiniGlobe from the repository linked here Content - MiniGlobe
2. Install via Joomla's Extension Manager (Extensions > Manage > Install).
3. Enable the plugin in the Plugin Manager (Extensions > Plugins, search for "Content - MiniGlobe").
4. Configure default settings in the plugin options (optional, see Configuration below).

Usage

Add the {miniglobe} tag to any Joomla article to embed a 3D globe. The simplest form is: 

{miniglobe}

This renders a globe using all default settings from the plugin configuration (texture, clouds, atmosphere, etc.). The globe automatically scales to fit the width of its container, making it responsive to your site's layout. The "mini" in MiniGlobe refers to its incredibly lightweight footprint (52KB core JavaScript, under 400KB with all features and textures), not its display size.

Tag Attributes

You can override default settings by adding attributes to the {miniglobe} tag. All attributes are optional, and unspecified attributes fall back to plugin defaults.

IMPORTANT CHANGES in 5.2+:

• markersAJAXInterval is now in milliseconds (was seconds in old version)
• hoverStop renamed to pauseOnHover
• bumpmap and related attributes removed (use texture with baked lighting instead)
• speed renamed to rotationSpeed and now uses radians instead of degrees
• New procedural rendering mode when textureImage="false"
• New atmospheric and graticule features

Example Tags

Basic globe with default settings:

{miniglobe}

Globe with procedural land/ocean colors (no texture required):

{miniglobe textureImage="false" oceanColor="[0.1,0.2,0.4]" landColor="[0.3,0.5,0.2]"}

Globe with a red sphere marker in New York City, brighter lighting, and clouds:

{miniglobe brightness="1.5" markers='[{"lat":40.7128,"lon":-74.0060,"size":0.02,"color":[1,0,0],"type":"sphere","id":"nyc"}]' cloudTextureImage="media/plg_content_miniglobe/images/clouds.webp"}

Globe with atmospheric glow and graticule grid:

{miniglobe fakeAtmosphere="1" graticule="1"}

Globe with dynamic markers updated every 10 seconds via AJAX:

{miniglobe markersAJAX="/path/to/markers.json" markersAJAXInterval="10000"}

Note: 10000 milliseconds = 10 seconds

Marker Format

New in 5.2+: Markers now use JSON objects (not arrays) and support intelligent updates with IDs.

Tag Attribute Format

For the markers attribute, provide a JSON array of marker objects:

[
  {
    "lat": 40.7128,
    "lon": -74.0060,
    "size": 0.02,
    "color": [1, 0, 0],
    "type": "sphere",
    "id": "nyc",
    "group": "cities"
  },
  {
    "lat": 51.5074,
    "lon": -0.1278,
    "size": 0.005,
    "color": [0, 1, 0],
    "type": "cylinder",
    "length": 0.15,
    "id": "london",
    "group": "cities"
  }
]

Marker Object Properties:

• lat (required): Latitude as a float (-90 to 90)
• lon (required): Longitude as a float (-180 to 180)
• type (optional): "sphere" or "cylinder" (default: "sphere")
• size (optional): Float, marker size (default: plugin's markerSize setting)
  • For spheres: radius
  • For cylinders: base radius
• length (optional): Float, cylinder height (only for type="cylinder", default: plugin's markerLength)
• color (optional): RGB array [r,g,b] (0-1 range) or hex string "#ff0000" (default: plugin's markerColor)
• id (optional but recommended): Unique string identifier for intelligent updates
• group (optional): String group name for bulk operations

AJAX/KML JSON Format

For markersAJAX, the JSON file must return an array of marker objects (same format as above):

[
  {"lat":40.7128,"lon":-74.0060,"size":0.02,"color":[1,0,0],"type":"sphere","id":"nyc","group":"usa"},
  {"lat":51.5074,"lon":-0.1278,"size":0.005,"color":[0,1,0],"type":"cylinder","length":0.15,"id":"london","group":"uk"}
]

Intelligent Updates: When markers are updated via AJAX or KML:

• Markers with existing IDs are updated (position, color, size)
• Markers with new IDs are added
• Markers no longer present are removed
• No jarring replacements - smooth, professional updates

Without IDs: If markers don't have IDs, they'll be assigned auto-generated IDs and treated as new markers on each update.

JavaScript Marker Control

MiniGlobe supports comprehensive marker control via JavaScript. Each globe is accessible via its container <div> (with plg_content_miniglobe class and a unique ID like miniglobe_0). Use the MiniGlobe property to access the API:

var container = document.getElementById('miniglobe_0');
var globe = container.MiniGlobe;

API Methods

addMarker(type, lat, lon, color, size, id, group, length)

Add a marker to the globe.

Parameters:

• type (string): "sphere" or "cylinder"
• lat (float): Latitude (-90 to 90)
• lon (float): Longitude (-180 to 180)
• color (array or null): RGB array [r,g,b] (0-1 range) or null for default
• size (float or null): Marker size or null for default
• id (string): Unique identifier (required for updates)
• group (string, optional): Group name for bulk operations
• length (float, optional): Cylinder height (only for type="cylinder")

Examples:

// Add a red sphere in New York
globe.addMarker('sphere', 40.7128, -74.0060, [1,0,0], 0.02, 'nyc', 'cities');

// Add a green cylinder in London using default size/color
globe.addMarker('cylinder', 51.5074, -0.1278, null, null, 'london', 'cities', 0.15);

removeMarker(id)

Remove a specific marker by its ID.

Parameters:

• id (string): The unique identifier of the marker to remove

Example:

globe.removeMarker('nyc');

removeMarkersByGroup(group)

Remove all markers in a specific group.

Parameters:

• group (string): The group name

Example:

// Remove all markers in the 'cities' group
globe.removeMarkersByGroup('cities');

updateMarker(id, properties)

Update an existing marker's properties.

Parameters:

• id (string): The unique identifier of the marker
• properties (object): Object with properties to update (lat, lon, color, size, length, type, group)

Example:

// Move NYC marker and change its color
globe.updateMarker('nyc', {
    lat: 40.7589,
    lon: -73.9851,
    color: [0, 0, 1]
});

clearMarkers()

Remove all markers from the globe.

Example:

globe.clearMarkers();

Complete Example

// Get the globe instance
var container = document.getElementById('miniglobe_0');
var globe = container.MiniGlobe;

// Add various markers
globe.addMarker('sphere', 40.7128, -74.0060, [1,0,0], 0.02, 'nyc', 'usa');
globe.addMarker('sphere', 34.0522, -118.2437, [1,0,0], 0.02, 'la', 'usa');
globe.addMarker('cylinder', 51.5074, -0.1278, [0,1,0], 0.005, 'london', 'uk', 0.15);

// Update a marker after 2 seconds
setTimeout(function() {
    globe.updateMarker('nyc', {color: [0,0,1], size: 0.03});
}, 2000);

// Remove all USA markers after 5 seconds
setTimeout(function() {
    globe.removeMarkersByGroup('usa');
}, 5000);

// Clear all markers after 10 seconds
setTimeout(function() {
    globe.clearMarkers();
}, 10000);

Nation Color Overlay Feature

MiniGlobe now supports highlighting individual nations with custom colors when using procedural rendering mode. This feature allows you to overlay specific countries with different colors on top of the base land/ocean colors.

How It Works

The nationColors property accepts an object mapping three-letter ISO country codes to RGB color arrays. When procedural mode is enabled (textureImage: false), MiniGlobe will render these nations with their assigned colors as semi-transparent overlays on the globe.

Usage

Setting Nation Colors

Nation colors can be set by directly assigning to the nationColors property after instantiation:

const globe = new MiniGlobe({
  canvas: document.getElementById('miniglobe_N'),
  textureImage: false,  // Required - nation colors only work in procedural mode
  oceanColor: [0.05, 0.15, 0.35],
  landColor: [0.2, 0.45, 0.15]
});

// Assign colors to specific nations
globe.nationColors = {
  'USA': [0.8, 0.2, 0.2],    // Red
  'CAN': [0.9, 0.3, 0.3],    // Lighter red
  'MEX': [0.3, 0.7, 0.3],    // Green
  'BRA': [1.0, 0.8, 0.0],    // Yellow
  'AUS': [0.2, 0.4, 0.8]     // Blue
};

Adding or Updating Individual Nations

You can add or modify nation colors at any time:

// Add a single nation color
globe.nationColors['GBR'] = [0.7, 0.1, 0.4];  // Purple

// Update an existing nation color
globe.nationColors['USA'] = [0.3, 0.3, 0.9];  // Change to blue

Removing Nation Colors

To remove a nation's color overlay:

// Remove a single nation
delete globe.nationColors['USA'];

// Clear all nation colors
globe.nationColors = {};

Important Notes

1. Procedural Mode Required: Nation colors only work when textureImage is set to false. If you're using a texture image for the globe, nation colors will not be rendered.

2. Color Format: Colors must be specified as RGB arrays with values ranging from 0.0 to 1.0:

   • [1.0, 0.0, 0.0] = Pure red
   • [0.0, 1.0, 0.0] = Pure green
   • [0.0, 0.0, 1.0] = Pure blue
   • [0.5, 0.5, 0.5] = Medium gray

3. Country Codes: Use three-letter ISO 3166-1 alpha-3 country codes (e.g., 'USA', 'GBR', 'JPN', 'AUS'). The available codes are:

   • AFG, AGO, ALB, AND, ARE, ARG, ARM, ATA, ATG, AUS, AUT, AZE, BDI, BEL, BEN, BFA, BGD, BGR, BHR, BHS, BIH, BLR, BLZ, BOL, BRA, BRB, BRN, BTN, BWA, CAF, CAN, CHE, CHL, CHN, CIV, CMR, COD, COG, COL, COM, CPV, CRI, CUB, CYN, CYP, CZE, DEU, DJI, DMA, DNK, DOM, DZA, ECU, EGY, ERI, ESP, EST, ETH, FIN, FJI, FRA, FSM, GAB, GBR, GEO, GHA, GIN, GMB, GNB, GNQ, GRC, GRD, GTM, GUY, HND, HRV, HTI, HUN, IDN, IND, IRL, IRN, IRQ, ISL, ISR, ITA, JAM, JOR, JPN, KAS, KAZ, KEN, KGZ, KHM, KIR, KNA, KOR, KOS, KWT, LAO, LBN, LBR, LBY, LCA, LIE, LKA, LSO, LTU, LUX, LVA, MAR, MCO, MDA, MDG, MDV, MEX, MHL, MKD, MLI, MLT, MMR, MNE, MNG, MOZ, MRT, MUS, MWI, MYS, NAM, NER, NGA, NIC, NLD, NOR, NPL, NRU, NZL, OMN, PAK, PAN, PER, PHL, PLW, PNG, POL, PRK, PRT, PRY, PSE, QAT, ROU, RUS, RWA, SAH, SAU, SDN, SEN, SGP, SLB, SLE, SLV, SMR, SOL, SOM, SRB, SSD, STP, SUR, SVK, SVN, SWE, SWZ, SYC, SYR, TCD, TGO, THA, TJK, TKM, TLS, TON, TTO, TUN, TUR, TWN, TZA, UGA, UKR, URY, USA, UZB, VAT, VCT, VEN, VNM, VUT, WSM, YEM, ZAF, ZMB, ZWE

4. Rendering: Nation overlays are rendered with alpha blending on top of the base procedural globe, allowing the underlying terrain to show through slightly.

Example: Creating a Heat Map

const globe = new MiniGlobe({
  canvas: document.getElementById('miniglobe_N'),
  textureImage: false,
  oceanColor: [0.05, 0.15, 0.35],
  landColor: [0.8, 0.8, 0.8],  // Light gray base
  rotationSpeed: 0.005
});

// Create a population density visualization
globe.nationColors = {
  'CHN': [0.9, 0.1, 0.1],  // High density - dark red
  'IND': [0.9, 0.1, 0.1],
  'USA': [0.9, 0.5, 0.2],  // Medium-high - orange
  'BRA': [0.9, 0.5, 0.2],
  'CAN': [0.4, 0.7, 0.4],  // Low density - green
  'AUS': [0.4, 0.7, 0.4]
};

Example: Highlighting Regions

const globe = new MiniGlobe({
  canvas: document.getElementById('miniglobe_N'),
  textureImage: false,
  oceanColor: [0.1, 0.2, 0.4],
  landColor: [0.3, 0.5, 0.2]
});

// Highlight European Union members in blue
const euCountries = ['AUT', 'BEL', 'BGR', 'HRV', 'CYP', 'CZE', 'DNK', 
                     'EST', 'FIN', 'FRA', 'DEU', 'GRC', 'HUN', 'IRL', 
                     'ITA', 'LVA', 'LTU', 'LUX', 'MLT', 'NLD', 'POL', 
                     'PRT', 'ROU', 'SVK', 'SVN', 'ESP', 'SWE'];

const euColor = [0.2, 0.4, 0.8];  // EU blue
euCountries.forEach(code => {
  globe.nationColors[code] = euColor;
});

Technical Details

The nation color feature uses:

• Nation masks: Compressed RLE-encoded bitmap data for each country's boundaries
• Texture generation: On-demand WebGL texture creation from decompressed masks
• Blended rendering: Nations are rendered with alpha blending for smooth overlay effects
• Shader mode: A special shader uniform (u_nationMode) switches between base and nation rendering

Performance Considerations

• Nation textures are cached after first use
• Only assigned nations generate textures (no overhead for unused countries)
• Rendering performance depends on the number of nations with assigned colors

Configuration

In the Joomla Plugin Manager, configure default settings for MiniGlobe:

Basic Settings:

• Pause on Hover: Enable/disable pause rotation when hovering (0 or 1)
• Rotation Speed: Globe rotation speed in radians per frame (e.g., 0.01)
• Brightness: Ambient light intensity (e.g., 1.0)

Texture Settings:

• Texture Image: Default equirectangular globe texture path (or "false" for procedural)
• Cloud Texture Image: Default equirectangular cloud texture path (or leave empty to disable)
• Ocean Color: Default RGB color for procedural oceans [r,g,b]
• Land Color: Default RGB color for procedural land [r,g,b]

Visual Effects:

• Fake Atmosphere: Enable/disable atmospheric glow (0 or 1)
• Graticule: Enable/disable lat/lon grid lines (0 or 1)
• Grid Color: Default RGB color for graticule [r,g,b]
• Cloud Rotation Speed: Relative speed of cloud rotation (e.g., 1.5)
• Cloud Scale: Cloud layer size relative to globe (e.g., 1.01)
• Cloud Opacity: Cloud transparency (0-1, e.g., 0.8)

Marker Settings:

• Marker Color: Default RGB color [r,g,b] or hex string
• Marker Size: Default size as radius (e.g., 0.02)
• Marker Length: Default cylinder height (e.g., 0.1)

Tag attributes override these defaults.

Texture Requirements

All textures (globe, clouds) must be in equirectangular projection (also called "plate carrée" or "geographic projection").

Recommended sizes:

• 1024x512: Good balance of quality and file size (~100-200KB as WebP)
• 2048x1024: High quality for larger displays (~300-500KB as WebP)
• 4096x2048: Maximum quality for 4K displays (~800KB-1.5MB as WebP)

Format recommendations:

Texture sources:

• NASA Visible Earth (https://visibleearth.nasa.gov/)
• Natural Earth (https://www.naturalearthdata.com/)
• Textures.com
• Custom creation with the Equirectangular Globe Texture Editor

Procedural Mode: Set textureImage="false" to skip textures entirely and use color-based land/ocean rendering. This is the smallest option (no texture download) and allows easy color customization.

Advanced Features

Procedural Rendering

Skip texture files entirely and render land/ocean with solid colors:

{miniglobe textureImage="false" oceanColor="[0.1,0.2,0.4]" landColor="[0.3,0.6,0.2]"}

This uses an embedded RLE-compressed land mask for accurate coastlines without any external files.

Atmospheric Glow

Add a subtle atmospheric halo around the globe:

{miniglobe fakeAtmosphere="1"}

Graticule Grid

Display latitude and longitude lines:

{miniglobe graticule="1" gridColor="[0.5,0.5,0.5]"}

Customize grid appearance:

• gridThickness: Line thickness (default: 0.0015)
• lonInterval: Degrees between longitude lines (default: 30)
• latInterval: Degrees between latitude lines (default: 15)
• boldEquator: Make equator thicker (default: true)
• boldTropics: Highlight tropic lines (default: false)
• poleFade: Fade grid near poles (default: true)

Independent Cloud Rotation

Clouds can rotate at a different speed than the globe:

{miniglobe cloudTextureImage="path/to/clouds.webp" cloudRotationSpeed="1.5"}

A cloudRotationSpeed of 1.5 means clouds rotate 50% faster than the globe.

Marker Types

Sphere markers: Best for point locations

globe.addMarker('sphere', 40.7128, -74.0060, [1,0,0], 0.02, 'id', 'group');

Cylinder markers: Best for vertical data (heights, values, intensity)

globe.addMarker('cylinder', 40.7128, -74.0060, [0,1,0], 0.005, 'id', 'group', 0.15);

Performance Notes

File Sizes:

• Core JavaScript: 52KB minified
• With 1024x512 WebP texture: ~150-250KB total
• With 2048x1024 WebP texture + clouds: ~350-450KB total
• Procedural mode (no textures): 52KB total

Browser Requirements:

• WebGL2 support required
• Works on all modern browsers (Chrome, Firefox, Safari, Edge)
• Mobile-optimized for smooth performance on phones/tablets

Multiple Globes:

• Uses shared Web Worker for efficient AJAX/KML loading
• Multiple globes on one page share resources efficiently
• Each globe maintains independent state

Optimization Tips:

1. Use WebP format for textures (50-70% smaller than PNG)
2. Use 1024x512 textures unless you need 4K quality
3. Consider procedural mode for minimal file size
4. Set appropriate markersAJAXInterval (don't poll too frequently)
5. Use marker IDs for efficient updates

Notes

• MiniGlobe requires WebGL2 support in the browser (all modern browsers since 2017)
• The plugin is lightweight: 52KB core JavaScript with no external dependencies
• Three.js has been removed - now uses pure WebGL2 rendering
• The globe scales to the full width of its container, making it responsive
• Ensure markersAJAX URLs return valid JSON in the correct format
• markersAJAXInterval is in milliseconds (10000 = 10 seconds)
• Marker updates are intelligent - only changes what's needed (no jarring replacements)
• Use WebP or JPEG for textures to optimize performance
• Cloud layer is optional and can be disabled to reduce file size
• Procedural rendering (textureImage="false") provides the smallest footprint
• Multiple globes on one page share a Web Worker for efficient resource usage

Migration from 5.1.x to 5.2+

If you're upgrading from the Three.js-based version, here are the key changes:

Tag Attribute Changes:

• speed → rotationSpeed (now in radians instead of degrees)
• hoverStop → pauseOnHover
• bumpmap removed (use textures with baked lighting)
• bumpmapImage removed
• markersAJAXInterval now in milliseconds (was seconds)
• markers now uses object format instead of array format

JavaScript API Changes:

• addMarker(lat, lon, size, color) → addMarker(type, lat, lon, color, size, id, group, length)
• removeMarker(index) → removeMarker(id) (now uses ID instead of index)
• removeMarkers([indices]) → removeMarkersByGroup(group) or clearMarkers()
• processMarkersArray(array) → Handled automatically via intelligent updates
• New methods: updateMarker(), removeMarkersByGroup()

Visual Changes:

• Globe may appear slightly different due to WebGL2 rendering vs Three.js
• Better performance and smoother animations
• New optional features: atmosphere, graticule, procedural rendering

File Size:

• 700KB → 52KB (92% reduction)
• No Three.js dependency to load

Breaking Changes:

• Old marker array format [[lat,lon,size,color]] still works but object format recommended
• JavaScript API method signatures have changed
• Speed values need adjustment (radians vs degrees)

Troubleshooting

Globe doesn't appear:

• Check browser console for WebGL2 errors
• Verify the plugin is enabled in Plugin Manager
• Ensure texture paths are correct and files exist
• If you have CSP headers, ensure worker-src allows blob:

Markers don't update:

• Check that markersAJAXInterval is in milliseconds (10000 = 10 seconds)
• Verify JSON format matches the object structure
• Check browser console for fetch errors
• Ensure URLs are absolute or correctly relative

Performance issues:

• Reduce texture size (use 1024x512 instead of 2048x1024)
• Disable clouds if not needed
• Reduce marker count or update frequency
• Consider procedural rendering instead of textures

Markers flash/disappear on update:

• Add unique id properties to each marker
• This enables intelligent updates instead of full replacement