OpenLIME

Class: Layer

Layer

Layer is the core class for rendering content in OpenLIME. It manages raster data display, tile loading, and shader-based rendering.

Features:

  • Tile-based rendering with level-of-detail
  • Shader-based visualization effects
  • Automatic tile prefetching and caching
  • Coordinate system transformations
  • Animation and interpolation of shader parameters
  • Support for multiple visualization modes
  • Integration with layout systems for different data formats

Layers can be used directly or serve as a base class for specialized layer types. The class uses a registration system where derived classes register themselves, allowing instantiation through the 'type' option.

new Layer( [options])

Creates a Layer. Additionally, an object literal with Layer options can be specified. Signals are triggered when: ready: the size and layout of the layer is known update: some new tile is available, or some visualization parameters has changed loaded: is fired when all the images needed have been downloaded

Parameters:
Name Type Argument Description
options Object <optional>
Properties
Name Type Argument Default Description
layout string | Layout 'image'

The layout (the format of the input raster images).
type string

A string identifier to select the specific derived layer class to instantiate.
id string

The layer unique identifier.
label string

A string with a more comprehensive definition of the layer. If it exists, it is used in the UI layer menu, otherwise the id value is taken.
transform Transform

The relative coords from layer to canvas.
visible bool true

Whether to render the layer.
zindex number

Stack ordering value for the rendering of layers (higher zindex on top).
overlay bool false

Whether the layer must be rendered in overlay mode.
prefetchBorder number 1

The threshold (in tile units) around the current camera position for which to prefetch tiles.
mipmapBias number 0.2

Determine which texture is used when scale is not a power of 2. 0: use always the highest resulution, 1 the lowest, 0.5 switch halfway.
shaders Object

A map (shadersId, shader) of the shaders usable for the layer rendering. See @link {Shader}.
controllers Array.<Controller>

An array of UI device controllers active on the layer.
sourceLayer Layer

The layer from which to take the tiles (in order to avoid tile duplication).
debug boolean <optional>
 false

Enable debug output
Source:
Fires:
  • Layer#event:ready - Fired when layer is initialized
  • Layer#event:update - Fired when redraw is needed
  • Layer#event:loaded - Fired when all tiles are loaded
  • Layer#event:updateSize - Fired when layer size changes
Example
```javascript
// Create a basic image layer
const layer = new OpenLIME.Layer({
  layout: 'deepzoom',
  type: 'image',
  url: 'path/to/image.dzi',
  label: 'Main Image'
});

// Add to viewer
viewer.addLayer('main', layer);

// Listen for events
layer.addEvent('ready', () => {
  console.log('Layer initialized');
});
```

Methods

addControl(name, value)

Adds a shader parameter control

Parameters:
Name Type Description
name string

Control identifier
value *

Initial value
Source:
Throws:

If control already exists

Type
Error

addShader(id, shader)

Adds a shader to the layer's available shaders

Parameters:
Name Type Description
id string

Unique identifier for the shader
shader Shader

Shader instance to add
Source:
Throws:

If shader with the same id already exists

Type
Error
Returns:

This layer instance for method chaining

Type
Layer
Example
```javascript
const customShader = new OpenLIME.Shader({...});
layer.addShader('custom', customShader);
layer.setShader('custom');
```

addShaderFilter(filter)

Adds a filter to the current shader

Parameters:
Name Type Description
filter Object

Filter specification
Source:
Throws:

If no shader is set

Type
Error

boundingBox()

Gets layer bounding box in scene coordinates

Source:
Returns:

Bounding box

Type
BoundingBox

clearShaderFilters(name)

Removes all filters from the current shader

Parameters:
Name Type Description
name Object

Filter name
Source:
Throws:

If no shader is set

Type
Error

derive( [options])

Creates a new Layer that shares tiles with this layer but uses a different shader. This method allows efficient creation of derivative layers that share the same source textures, which is useful for applying different visual effects to the same image data without duplicating resources.

Parameters:
Name Type Argument Default Description
options Object <optional>
 {}

Options for the new layer

Properties
Name Type Argument Description
shaders Object <optional>

Map of shaders for the new layer
defaultShader string <optional>

ID of shader to set as active
label string <optional>

Label for the new layer (defaults to original label)
zindex number <optional>

Z-index for the new layer (defaults to original + 1)
visible boolean <optional>

Layer visibility (defaults to same as original)
transform Transform <optional>

Custom transform (defaults to copy of original)
mipmapBias number <optional>

Custom mipmap bias (defaults to original value)
pixelSize number <optional>

Custom pixel size (defaults to original value)
debug boolean <optional>

Debug mode flag (defaults to original value)
Source:
Returns:

A new layer sharing textures with this one

Type
Layer
Example
```javascript
// Create a derived layer with edge detection shader
const enhancedShader = new OpenLIME.ShaderEdgeDetection();
const derivedLayer = originalLayer.derive({
    label: 'Edge Detection',
    shaders: { 'edge': enhancedShader },
    defaultShader: 'edge',
    zindex: 10
});
viewer.addLayer('edges', derivedLayer);
```
or
```javascript
const enhancedShader = new OpenLIME.ShaderEdgeDetection();
const derivedLayer = layer.derive({
    label: 'Enhanced Image'
});
derivedLayer.addShader('enhanced', enhancedShader);
derivedLayer.setShader('enhanced');
viewer.addLayer('Enhanced Image', derivedLayer);
```

getControl(name)

Gets the shader parameter control corresponding to name

Parameters:
Name Type Description
name *

The name of the control. return {*} The control
Source:

getMode()

Gets the current shader visualization mode

Source:
Returns:

Current mode or null if no shader

Type
string | null

getModes()

Gets available shader modes

Source:
Returns:

Array of available modes

Type
Array.<string>

getPixelValues(x, y)

Gets pixel values for a specific pixel location Works with both single images and tiled formats

Parameters:
Name Type Description
x number

X coordinate in image space (0,0 at top-left)
y number

Y coordinate in image space (0,0 at top-left)
Source:
Returns:

Array containing RGBA values for each raster at the specified pixel

Type
Array.<Uint8Array>

getState( [stateMask])

Gets the current layer state

Parameters:
Name Type Argument Default Description
stateMask Object <optional>
 null

Optional mask to filter returned state properties
Source:
Returns:

Current state object

Type
Object

interpolateControls()

Updates control interpolation

Source:
Returns:

Whether all interpolations are complete

Type
boolean

<async> loadTile(tile, callback)

Loads and processes a single image tile with optimized resource management. Implements request batching, concurrent loading, and proper error handling.

Parameters:
Name Type Description
tile Object

Tile specification object

Properties
Name Type Argument Description
index string

Unique tile identifier
url string

Base URL for tile resource
start number <optional>

Start byte for partial content (for tarzoom)
end number <optional>

End byte for partial content (for tarzoom)
offsets Array.<Object> <optional>

Byte offsets for interleaved formats
callback function

Completion callback(error, size)
Source:
Throws:

If tile is already in processing queue

Type
Error
Returns:
Type
Promise.<void>

pixelSizePerMM()

Gets pixel size in millimeters

Source:
Returns:

Size of one pixel in mm

Type
number

removeShader(id)

Removes a shader from the layer's available shaders

Parameters:
Name Type Description
id string

Identifier of the shader to remove
Source:
Throws:

If shader with the specified id doesn't exist

Type
Error
Returns:

This layer instance for method chaining

Type
Layer
Example
```javascript
// Remove a shader that's no longer needed
layer.removeShader('oldEffect');
```

removeShaderFilter(name)

Removes a filter from the current shader

Parameters:
Name Type Description
name Object

Filter name
Source:
Throws:

If no shader is set

Type
Error

scale()

Gets layer scale

Source:
Returns:

Current scale value

Type
number

setControl(name, value [, dt] [, easing])

Sets a shader control value with optional animation

Parameters:
Name Type Argument Default Description
name string

Control identifier
value *

New value
dt number <optional>

Animation duration in ms
easing string <optional>
 'linear'

Easing function
Source:
Fires:

setMode(mode)

Sets shader visualization mode

Parameters:
Name Type Description
mode string

Mode to set
Source:
Fires:

setShader(id)

Sets the active shader

Parameters:
Name Type Description
id string

Shader identifier from registered shaders
Source:
Fires:
Throws:

If shader ID is not found

Type
Error

setState(state [, dt] [, easing])

Sets the layer state with optional animation

Parameters:
Name Type Argument Default Description
state Object

State object with controls and mode
dt number <optional>

Animation duration in ms
easing string <optional>
 'linear'

Easing function ('linear'|'ease-out'|'ease-in-out')
Source:

setTransform(tx)

Sets the layer's transform

Parameters:
Name Type Description
tx Transform

New transform
Source:
Fires:
  • Layer#event:updateSize

setViewport(view)

Sets the layer's viewport

Parameters:
Name Type Description
view Object

Viewport specification

Properties
Name Type Description
x number

X position
y number

Y position
dx number

Width
dy number

Height
Source:
Fires:

setVisible(visible)

Sets layer visibility

Parameters:
Name Type Description
visible boolean

Whether layer should be visible
Source:
Fires:

setZindex(zindex)

Sets layer rendering order

Parameters:
Name Type Description
zindex number

Stack order value
Source:
Fires:

<static> computeLayersBBox(layers, discardHidden)

Computes combined bounding box of multiple layers

Parameters:
Name Type Description
layers Object.<string, Layer>

Map of layers
discardHidden boolean

Whether to ignore hidden layers
Source:
Returns:

Combined bounding box

Type
BoundingBox

<static> computeLayersMinScale(layers, discardHidden)

Computes minimum scale across layers

Parameters:
Name Type Description
layers Object.<string, Layer>

Map of layers
discardHidden boolean

Whether to ignore hidden layers
Source:
Returns:

Minimum scale value

Type
number

Events

ready

The event is fired when a layer is initialized.

Source:

update

The event is fired if a redraw is needed.

Source: