OpenLIME

Class: LayoutTiles

LayoutTiles

The Layout class is responsible for specifying the data formats (images) managed by OpenLIME. All web single-resolution image types (jpg, png, gif, etc...) are supported as well as the most common tiled image formats (deepzoom, zoomify, IIIF, google maps), which are suitable for large images.

Single-resolution images

The URL is the address of the file (for instance, 'https://my.example/image.jpg').

Tiled images

They can be specified in a variety of ways depending on the format chosen.

  • deepzoom - The root tile of the image pyramid has a size > 1px (typical value is 254px). It is defined by the URL of the .dzi file (for instance, 'https://my.example/image.dzi'). See: DeepZoom
  • deepzoom1px - The root tile of the image pyramid has a size = 1px. It is defined by the URL of the .dzi file (for instance, 'https://my.example/image.dzi'). See: DeepZoom
  • google - The URL points directly to the directory containing the pyramid of images (for instance, 'https://my.example/image'). The standard does not require any configuration file, so it is mandatory to indicate in the options the width and height in pixels of the original image. See: Google Maps
  • zoomify - The URL indicates the location of Zoomify configuration file (for instance, 'https://my.example/image/ImageProperties.xml'). See: Zoomify
  • iip - The server parameter (optional) indicates the URL of the IIPImage endpoint (for example '/fcgi-bin/iipsrv.fcgi'). The URL parameter indicates either just the name of the path and image file (for instance 'image.tif') if the server parameter has been set or the full IIP URL if not (for instance '/fcgi-bin/iipsrv.fcgi?FIF=image.tif' or 'https://you.server//fcgi-bin/iipsrv.fcgi?FIF=image.tif' if image is hosted elsewhere) See: IIPImage Server
  • iiif - According to the standard, the URL is the address of a IIIF server (for instance, 'https://myiiifserver.example/'). See: IIIF
  • tarzoom and itarzoom - This is a custom format of the OpenLIME framework. It can be described as the TAR of a DeepZoom (all the DeepZoom image pyramid is stored in a single file). It takes advantage of the fact that current web servers are able to handle partial-content HTTP requests. Tarzoom facilitates the work of the server, which is not penalised by having to manage a file system with many small files. The URL is the address of the .tzi file (for instance, 'https://my.example/image.tzi'). Warning: tarzoom|itarzoom may not work on older web servers.

new LayoutTiles(url, type [, options])

Creates a new LayoutTiles instance.

Parameters:
Name Type Argument Description
url string

URL to the image or tile configuration
type Layout#Type

The type of image layout
options Object <optional>

Configuration options

Properties
Name Type Argument Default Description
width number <optional>

Width of original image (required for 'google' type)
height number <optional>

Height of original image (required for 'google' type)
suffix string <optional>
 'jpg'

Tile file extension
subdomains string <optional>
 'abc'

Available subdomains for Google URL template
cachelevels number <optional>
 10

Number of levels above current to cache
server string <optional>

IIP server URL (for IIP type only)
Source:
Fires:
  • Layout#event:ready - When layout initialization is complete
  • Layout#event:updateSize - When layout dimensions change
Example
```javascript
// DeepZoom layout
const dzLayout = new LayoutTiles('image.dzi', 'deepzoom', {
  cachelevels: 8
});

// Google Maps layout
const googleLayout = new LayoutTiles('tiles/', 'google', {
  width: 4096,
  height: 3072,
  suffix: 'png'
});

// IIIF layout
const iiifLayout = new LayoutTiles('https://server/image', 'iiif');
```

Extends

Methods

available(viewport, transform, layerTransform, border, bias, tiles)

Gets tiles currently available for rendering.

Parameters:
Name Type Description
viewport Viewport

Current viewport
transform Transform

Current transform
layerTransform Transform

Layer-specific transform
border number

Border size in tile units
bias number

Resolution bias
tiles Map.<number, Tile>

Available tiles
Overrides:
Source:
Returns:

Map of tile index to tile object with additional 'complete' property

Type
Object.<number, Tile>

boundingBox()

Gets layout bounds

Inherited From:
Overrides:
Source:
Returns:

Layout boundaries

Type
BoundingBox

getTileSize()

Gets the tile size for the layout.

Overrides:
Source:
Returns:

Array containing [width, height] of tiles

Type
Array.<number>

getTileURL(id, tile)

Gets URL for a specific tile.

Parameters:
Name Type Description
id number

Channel/raster ID
tile TileObj

Tile to get URL for
Overrides:
Source:
Throws:

If layout not defined or ready

Type
Error
Returns:

URL to fetch tile data

Type
string

getViewportBox(viewport, transform, layerT)

Calculates viewport bounding box

Parameters:
Name Type Description
viewport Object

Viewport parameters
transform Transform

Current transform
layerT Transform

Layer transform
Inherited From:
Overrides:
Source:
Returns:

Viewport bounds in image space

Type
BoundingBox

index(level, x, y)

Generates unique index for a tile based on its position and level.

Parameters:
Name Type Description
level number

Zoom level
x number

X coordinate
y number

Y coordinate
Source:
Returns:

Unique tile index

Type
number

needed(viewport, transform, layerTransform, border, bias, tiles [, maxtiles])

Determines which tiles are needed for the current view.

Parameters:
Name Type Argument Default Description
viewport Viewport

Current viewport
transform Transform

Current transform
layerTransform Transform

Layer-specific transform
border number

Border size in tile units for prefetching
bias number

Resolution bias (0-1, affects mipmap level selection)
tiles Map.<number, Tile>

Currently available tiles
maxtiles number <optional>
 8

Maximum number of tiles to return
Overrides:
Source:
Returns:

Array of needed tiles sorted by priority

Type
Array.<TileObj>

neededBox(viewport, transform, layerTransform, border, bias)

Computes required tiles at each pyramid level for the current view.

Parameters:
Name Type Description
viewport Viewport

Current viewport
transform Transform

Current transform
layerTransform Transform

Layer-specific transform
border number

Border size in tile units for prefetching
bias number

Resolution bias (0-1)
Source:
Returns:

  • Tile requirements

    Type
    Object

  • .level - Optimal pyramid level

    Type
    number

  • .pyramid - Array of tile bounding boxes per level

    Type
    Array.<BoundingBox>

newTile(index)

Creates a new tile instance with computed properties.

Parameters:
Name Type Description
index number

Unique tile identifier
Overrides:
  • Layout#newTile
Source:
Returns:

New tile instance

Type
TileObj

reverseIndex(index)

Converts tile index back to level, x, y coordinates.

Parameters:
Name Type Description
index number

Tile index
Source:
Returns:

Position object containing level, x, y

Type
Object

tileCoords(tile)

Gets coordinates for a tile in both image space and texture space.

Parameters:
Name Type Description
tile TileObj

The tile to get coordinates for
Overrides:
Source:
Returns:

  • Coordinate data

    Type
    Object

  • .coords - Image space coordinates [x,y,z, x,y,z, x,y,z, x,y,z]

    Type
    Float32Array

  • .tcoords - Texture coordinates [u,v, u,v, u,v, u,v]

    Type
    Float32Array

Type Definitions

Type

Supported image layout types including both single-resolution and multi-resolution formats.

  • image: Standard web image formats (jpg, png, gif, etc.)
  • deepzoom: Microsoft Deep Zoom format with root tile > 1px
  • deepzoom1px: Microsoft Deep Zoom format with 1px root tile
  • google: Google Maps tiling scheme
  • zoomify: Zoomify tiling format
  • iiif: International Image Interoperability Framework
  • iip: Internet Imaging Protocol
  • tarzoom: OpenLIME custom format (single TAR of DeepZoom pyramid)
  • itarzoom: OpenLIME custom interleaved TAR format
Type:
  • 'image' | 'deepzoom' | 'deepzoom1px' | 'google' | 'zoomify' | 'iiif' | 'iip' | 'tarzoom' | 'itarzoom'
Inherited From:
Overrides:
Source:

Events

ready

The event is fired when a layout is ready to be drawn(the single-resolution image is downloaded or the multi-resolution structure has been initialized).

Inherited From:
Overrides:
Source:

updateSize

The event is fired when a layout size is modified (and the scene extension must be recomputed at canvas level).

Inherited From:
Overrides:
Source: