Struct AdvancedCogViewer 

pub struct AdvancedCogViewer { /* private fields */ }

Advanced COG viewer with comprehensive tile management and caching

This is the recommended viewer for production applications. It provides advanced features including:

• LRU Tile Caching: Automatic memory management with configurable size
• Viewport Management: Pan, zoom, and viewport history (undo/redo)
• Prefetching: Intelligent prefetching of nearby tiles
• Multi-resolution: Automatic selection of appropriate overview level
• Image Processing: Built-in contrast enhancement and statistics
• Performance Tracking: Cache hit rates and loading metrics

Memory Management

The viewer uses an LRU (Least Recently Used) cache to manage memory efficiently. When the cache is full, the least recently accessed tiles are evicted. Configure the cache size based on your application’s memory constraints and typical usage patterns.

Recommended cache sizes:

• Mobile devices: 50-100 MB
• Desktop browsers: 100-500 MB
• High-end workstations: 500-1000 MB

Prefetching Strategies

The viewer supports multiple prefetching strategies:

• None: No prefetching (lowest memory, highest latency)
• Neighbors: Prefetch immediately adjacent tiles
• Pyramid: Prefetch parent and child tiles (smooth zooming)

Performance Optimization

For best performance:

1. Use an appropriate cache size (100-200 MB recommended)
2. Enable prefetching for smoother user experience
3. Use viewport management to minimize unnecessary tile loads
4. Monitor cache statistics to tune parameters

Example

const viewer = new AdvancedCogViewer();
await viewer.open('<https://example.com/image.tif>', 100); // 100MB cache

// Setup viewport
viewer.setViewportSize(800, 600);
viewer.fitToImage();

// Enable prefetching
viewer.setPrefetchStrategy('neighbors');

// Load and display tiles
const imageData = await viewer.readTileAsImageData(0, 0, 0);
ctx.putImageData(imageData, 0, 0);

// Check performance
const stats = JSON.parse(viewer.getCacheStats());
console.log(`Hit rate: ${stats.hit_count / (stats.hit_count + stats.miss_count)}`);

Implementations

impl AdvancedCogViewer

pub fn new() -> Self

Creates a new advanced COG viewer

pub async fn open( &mut self, url: &str, cache_size_mb: usize, ) -> Result<(), JsValue>

Opens a COG file from a URL with advanced caching enabled

This method initializes the viewer with full caching and viewport management. It performs the following operations:

1. Initial Connection: Sends HEAD request to validate URL and check range support
2. Header Parsing: Fetches and parses TIFF header (8-16 bytes)
3. Metadata Extraction: Parses IFD to extract image dimensions, tile size, bands
4. GeoTIFF Tags: Extracts coordinate system information (EPSG, geotransform)
5. Pyramid Creation: Builds tile pyramid structure for all overview levels
6. Cache Initialization: Creates LRU cache with specified size
7. Viewport Setup: Initializes viewport with default settings

Arguments

• url - The URL of the COG file. Must support HTTP range requests (Accept-Ranges: bytes) and have proper CORS headers configured.
• cache_size_mb - Size of the tile cache in megabytes. Recommended values:
  • Mobile: 50-100 MB
  • Desktop: 100-500 MB
  • High-end: 500-1000 MB

Returns

Returns Ok(()) on successful initialization, or a JavaScript error on failure.

Errors

This method can fail for several reasons:

Network Errors

• Connection timeout
• DNS resolution failure
• SSL/TLS errors

HTTP Errors

• 404 Not Found: File doesn’t exist at the URL
• 403 Forbidden: Access denied
• 500 Server Error: Server-side issues

CORS Errors

• Missing Access-Control-Allow-Origin header
• Missing Access-Control-Allow-Headers for range requests

Format Errors

• Invalid TIFF magic bytes
• Corrupted IFD structure
• Unsupported TIFF variant
• Missing required tags

Performance Considerations

Opening a COG typically requires 2-4 HTTP requests:

1. HEAD request (~10ms)
2. Header fetch (~20ms for 16 bytes)
3. IFD fetch (~50ms for typical IFD)
4. GeoTIFF tags fetch (~30ms if separate)

Total typical open time: 100-200ms on good connections.

Example

const viewer = new AdvancedCogViewer();

try {
    // Open with 100MB cache
    await viewer.open('<https://example.com/landsat8.tif>', 100);

    console.log(`Opened: ${viewer.width()}x${viewer.height()}`);
    console.log(`Tiles: ${viewer.tile_width()}x${viewer.tile_height()}`);
    console.log(`Cache size: 100 MB`);
} catch (error) {
    if (error.message.includes('404')) {
        console.error('File not found');
    } else if (error.message.includes('CORS')) {
        console.error('CORS not configured. Add these headers:');
        console.error('  Access-Control-Allow-Origin: *');
        console.error('  Access-Control-Allow-Headers: Range');
    } else {
        console.error('Failed to open:', error.message);
    }
}

See Also

• WasmCogViewer::open() - Simple version without caching
• set_prefetch_strategy() - Configure prefetching after opening
• get_cache_stats() - Monitor cache performance

pub fn width(&self) -> u64

Returns the image width

pub fn height(&self) -> u64

Returns the image height

pub fn tile_width(&self) -> u32

Returns the tile width

pub fn tile_height(&self) -> u32

Returns the tile height

pub fn band_count(&self) -> u32

Returns the number of bands

pub fn overview_count(&self) -> usize

Returns the number of overview levels

pub fn epsg_code(&self) -> Option<u32>

Returns the EPSG code if available

pub fn url(&self) -> Option<String>

Returns the URL

pub fn set_viewport_size(&mut self, width: u32, height: u32)

Sets the viewport size

pub fn pan(&mut self, dx: f64, dy: f64)

Pans the viewport

pub fn zoom_in(&mut self)

Zooms in

pub fn zoom_out(&mut self)

Zooms out

pub fn set_zoom(&mut self, zoom: u32)

Sets the zoom level

pub fn center_on(&mut self, x: f64, y: f64)

Centers the viewport on a point

pub fn fit_to_image(&mut self)

Fits the viewport to the image

pub fn get_viewport(&self) -> Option<String>

Returns the current viewport as JSON

pub fn get_cache_stats(&self) -> Option<String>

Returns cache statistics as JSON

pub fn clear_cache(&mut self)

Clears the tile cache

pub fn set_prefetch_strategy(&mut self, strategy: &str)

Sets the prefetch strategy

pub fn get_metadata(&self) -> String

Returns comprehensive metadata as JSON

pub async fn compute_stats( &self, level: usize, tile_x: u32, tile_y: u32, ) -> Result<String, JsValue>

Computes image statistics for a region

pub async fn compute_histogram( &self, level: usize, tile_x: u32, tile_y: u32, ) -> Result<String, JsValue>

Computes histogram for a region (tile)

Returns a comprehensive JSON object containing:

• Image dimensions (width, height, total_pixels)
• Per-channel histograms (red, green, blue, luminance)
• Statistics for each channel (min, max, mean, median, std_dev, count)
• Histogram bins (256 bins for 8-bit values)

Arguments

• level - Overview/pyramid level (0 = full resolution)
• tile_x - Tile X coordinate
• tile_y - Tile Y coordinate

Example

const viewer = new AdvancedCogViewer();
await viewer.open('<https://example.com/image.tif>', 100);

// Get histogram for tile at (0, 0) at full resolution
const histogramJson = await viewer.computeHistogram(0, 0, 0);
const histogram = JSON.parse(histogramJson);

console.log(`Luminance mean: ${histogram.luminance.mean}`);
console.log(`Luminance std_dev: ${histogram.luminance.std_dev}`);
console.log(`Red min/max: ${histogram.red.min} - ${histogram.red.max}`);

pub async fn read_tile_cached( &mut self, level: usize, tile_x: u32, tile_y: u32, ) -> Result<Vec<u8>, JsValue>

Reads a tile with caching

pub async fn read_tile_as_image_data( &mut self, level: usize, tile_x: u32, tile_y: u32, ) -> Result<ImageData, JsValue>

Reads a tile as ImageData with caching

pub async fn read_tile_with_contrast( &mut self, level: usize, tile_x: u32, tile_y: u32, method: &str, ) -> Result<ImageData, JsValue>

Applies contrast enhancement to a tile

Trait Implementations

impl Default for AdvancedCogViewer

fn default() -> Self

Returns the “default value” for a type.

impl From<AdvancedCogViewer> for JsValue

fn from(value: AdvancedCogViewer) -> Self

Converts to this type from the input type.

impl FromWasmAbi for AdvancedCogViewer

type Abi = u32

The Wasm ABI type that this converts from when coming back out from the ABI boundary.

unsafe fn from_abi(js: u32) -> Self

Recover a Self from Self::Abi.

impl IntoWasmAbi for AdvancedCogViewer

type Abi = u32

The Wasm ABI type that this converts into when crossing the ABI boundary.

fn into_abi(self) -> u32

Convert self into Self::Abi so that it can be sent across the wasm ABI boundary.

impl LongRefFromWasmAbi for AdvancedCogViewer

type Abi = u32

Same as RefFromWasmAbi::Abi

type Anchor = RcRef<AdvancedCogViewer>

Same as RefFromWasmAbi::Anchor

unsafe fn long_ref_from_abi(js: Self::Abi) -> Self::Anchor

Same as RefFromWasmAbi::ref_from_abi

impl OptionFromWasmAbi for AdvancedCogViewer

fn is_none(abi: &Self::Abi) -> bool

Tests whether the argument is a “none” instance. If so it will be deserialized as None, and otherwise it will be passed to FromWasmAbi.

impl OptionIntoWasmAbi for AdvancedCogViewer

fn none() -> Self::Abi

Returns an ABI instance indicating “none”, which JS will interpret as the None branch of this option.

impl RefFromWasmAbi for AdvancedCogViewer

type Abi = u32

The Wasm ABI type references to Self are recovered from.

type Anchor = RcRef<AdvancedCogViewer>

The type that holds the reference to Self for the duration of the invocation of the function that has an &Self parameter. This is required to ensure that the lifetimes don’t persist beyond one function call, and so that they remain anonymous.

unsafe fn ref_from_abi(js: Self::Abi) -> Self::Anchor

Recover a Self::Anchor from Self::Abi.

impl RefMutFromWasmAbi for AdvancedCogViewer

type Abi = u32

Same as RefFromWasmAbi::Abi

type Anchor = RcRefMut<AdvancedCogViewer>

Same as RefFromWasmAbi::Anchor

unsafe fn ref_mut_from_abi(js: Self::Abi) -> Self::Anchor

Same as RefFromWasmAbi::ref_from_abi

impl TryFromJsValue for AdvancedCogViewer

fn try_from_js_value(value: JsValue) -> Result<Self, JsValue>

Performs the conversion.

fn try_from_js_value_ref(value: &JsValue) -> Option<Self>

Performs the conversion.

impl VectorFromWasmAbi for AdvancedCogViewer

type Abi = <Box<[JsValue]> as FromWasmAbi>::Abi

unsafe fn vector_from_abi(js: Self::Abi) -> Box<[AdvancedCogViewer]>

impl VectorIntoWasmAbi for AdvancedCogViewer

type Abi = <Box<[JsValue]> as IntoWasmAbi>::Abi

fn vector_into_abi(vector: Box<[AdvancedCogViewer]>) -> Self::Abi

impl WasmDescribe for AdvancedCogViewer

fn describe()

impl WasmDescribeVector for AdvancedCogViewer

fn describe_vector()

impl SupportsConstructor for AdvancedCogViewer

impl SupportsInstanceProperty for AdvancedCogViewer

impl SupportsStaticProperty for AdvancedCogViewer