Class: Piwakawaka

Piwakawaka(config, playCallback, stopCallback)

Pīwakawaka IIIF Image Navigator

A controlled experience of an IIIF image in an OpenSeadragon (OSD) viewer.

The Pīwakawaka library adds a wrapper around an OpenSeadragon viewer object (designed to present zoomable IIIF images). It takes over control of OpenSeadragon, presenting selected points of interest (using pan, zoom, pauses, and labels) in a configurable sequence.

Source: GitHub repository

Requires:

  • OpenSeadragon - <script src="https://cdnjs.cloudflare.com/ajax/libs/openseadragon/2.3.1/openseadragon.min.js"></script>
  • NoSleep.js - <script src="https://cdn.rawgit.com/richtr/NoSleep.js/v0.7.1/dist/NoSleep.js"></script>

Implementation notes

OpenSeadragon uses three image co-ordinate systems:

  1. image = pixels of the source image (as at original/100% resolution) e.g. width: 0-4000, height: 0-5000
  2. viewport = percentage of the source image e.g. width: 0 - 1, height: 0 - 1
  3. web container = pixels of the HTML element showing a part of the source image e.g. width: 0 - 300, height: 0 - 400

Most calculations here use source image co-ordinates (1 above), which are converted to/from viewport or web co-ordinates as necessary for OSD operations. While this does increase the number of calculations/conversions, it makes it easier to define locations to show, e.g. it is easier to specify a region of an image when looking at the original image in image editor software.

Regions are specified as rectangles, following OSD's Rect structure (excluding rotation) as {x,y,w,h}:

  • x = horizontal position of the top-left corner of the region rectangle, where 0 is the left edge of the source image
  • y = vertical position of the top-left corner of the region rectangle, where 0 is the top edge of the source image
  • w = horizontal width of the rectangle (to the right)
  • h = vertical height of the rectangle (downwards)

For example, {20,40,300,500} defines a rectangle that starts 20 pixels from the left edge of the source image and 40 pixels from its top, then extends 300 pixels to the right and 500 pixels downwards.

Pīwakawaka name

Named after the Pīwakawaka (pee-wahkah-wahkah) bird (New Zealand Fantail) which typically flits about constantly from place to place looking for tasty morsels.

Constructor

new Piwakawaka(config, playCallback, stopCallback)

Constructs a Pīwakawaka image navigator wrapper around an OpenSeadragon viewer.

Parameters:
Name Type Description
config Object

Configuration JSON
playCallback function

Callback function to call when play begins/resumes
stopCallback function

Callback function to call when play stops
Source:

Members

(static, constant) defaultFillViewer :Boolean

Default whether full view fills screen (crops), or letterboxed.

Type:
  • Boolean
Default Value:
  • true
Source:

(static, constant) defaultSpeedFactor :Number

Default pan speed adjustment factor (over the base speed).

Type:
  • Number
Default Value:
  • 10
Source:

(static, constant) defaultSpeedWebPixelsPerSecond :Number

Default base speed for panning in webpage pixels per seconds.

Type:
  • Number
Default Value:
  • 10
Source:

(static, constant) defaultSpringStiffness :Number

Default pan movement stiffness (1 = linear).

Type:
  • Number
Default Value:
  • 1
Source:

Methods

(static) calcDirectDistance(startX, startY, endX, endY) → {Number}

Calculates the distance in pixels of a direct/diagonal line from the specified start point (x,y) to the specified end point (x,y).

Parameters:
Name Type Description
startX Number
startY Number
endX Number
endY Number
Source:
Returns:

Approximate distance in pixels

Type
Number

(static) getParameterByName(parameterName, url) → {Number}

Retrieves the value of the specified parameter name from the querystring in the supplied URL.

Parameters:
Name Type Description
parameterName String

Querystring parameter name
url String

URL (use null for the current webpage URL)
Source:
Returns:

Parameter's value

Type
Number

applyAnimationDuration(secs)

Sets the specified animation duration (adjusted by the current speed factor) in the underlying OpenSeadragon viewer. Applies to all subsequent pan movements. If current speed factor is less than zero, the duration is set at 0 seconds.

Parameters:
Name Type Description
secs Number

Pan duration in seconds
Source:

applyMoveTo(targetX, targetY, targetWidth, targetHeight, label, duration, speedFactor, springStiffness, skipCondition)

Instructs the the underlying OpenSeadragon viewer to pan and zoom so that it shows the specified part of the image (specified using a rectangle's dimensions) in the visible webpage container.

If a speed factor is specified, it is used for this move only (afterwards the speed factor reverts to its previous value).

Parameters:
Name Type Description
targetX Number

Target rectangle's left side in image pixels
targetY Number

Target rectangle's top side in image pixels
targetWidth Number

Target rectangle's width in image pixels
targetHeight Number

Target rectangle's height in image pixels
label String

Label to display in an overlay
duration Number

Duration in secs for this movement only (overrides speed factor)
speedFactor Number

Speed factor to use for this movement only
springStiffness Number

Spring stiffness to use for this movement only
skipCondition String

Condition that (if true) will trigger that this action should be skipped
Source:

applySpringStiffness(springStiffness)

Sets the spring stiffness in the underlying OpenSeadragon viewer. Adjusts how 'springy' all subsequent pan movements appears.

Higher is less linear, e.g.

  • 1 = linear (pan exactly the same speed throughout the move)
  • 2 = some spring (starts slow, speeds up, then slows as arrives)
Parameters:
Name Type Description
springStiffness Number

Spring stiffness
Source:

commandToImagePixel(value, dimension) → {Number}

Converts movement commands to actual target image pixels. Known commands are converted to numbers, anything else (numbers or unknown commands) are returned unchanged. Calculates locations along the single dimension specified.

Commands:

  • min = minimum image pixel on this dimension (0 or cropped min)
  • max = maximum image pixel on this dimension (image or cropped max)
  • same = current image pixel location (i.e. no change)
  • next = location that scrolls forward by the size that is currently visible
  • prev = location that scrolls backwards by the size that is currently visible
Parameters:
Name Type Description
value String

Pixel {Number}, or command {String} to convert to pixel
dimension String

Dimension: x (horizontal, default), y (vertical)
Source:
Returns:

Calculated target pixel value

Type
Number

doNextSequenceAction()

Retrieves the next step in the sequence and performs its action. If there are no more steps, it calls stop().

Source:

getCurrentImageVisibleRegion() → {OpenSeadragon.Rect}

Retrieves the image dimensions of the part of the image that is currently visible in the webpage container. The pixels are coordinates within the source image - as at it's original 100% resolution. The returned rectangle is described as: x,y of the top left corner, plus the rectangle's width and height.

Source:
Returns:

Image pixels currently visable in the webpage container

Type
OpenSeadragon.Rect

getCurrentViewportVisibleRegion() → {OpenSeadragon.Rect}

Retrieves the viewport dimensions of the part of the image that is currently visible in the webpage container. The pixels are coordinates within the Viewport (OSD's special layer over the entire source image). The returned rectangle is described as: x,y of the top left corner, plus the rectangle's width and height.

Source:
Returns:

Viewport bounds currently visable in the webpage container

Type
OpenSeadragon.Rect

init(config)

Stores the supplied configuration. Only stores non-empty supplied properties (other existing properties are unchanged).

Parameters:
Name Type Description
config Object

Configuration JSON
Source:

initConditions()

Resets all conditions that trigger whether actions should be skipped.

Conditions:

  • overEdge = 'prev' or 'next' attempt would move beyond the edge of the image
Source:

initViewer(imageUrl)

Creates an OpenSeadragon (OSD) viewer for the specified image. The viewer is locked down so the user can't do much - this navigator will control it.

Parameters:
Name Type Description
imageUrl String

IIIF Image URL (info.json)
Source:

play(fromStepNo)

Starts automated play of the currently configured Pīwakawaka sequence.

If full screen mode is enabled, switches the view and activates no-sleep. NB: This step must be called as the result of a user action - Web browsers do not allow scripts to switch to full screen by themselves.

Parameters:
Name Type Default Description
fromStepNo Number 0

Step in the sequence to play from, 0=step 1, empty=step 1, -1=resume
Source:

resume()

Convenience method to play from the current step.

Source:

setCrop(x, y, width, height)

Sets a cropped rectangle area within the image in the config, so auto-pan operations stay within the cropped box. All parameters are mandatory. If any are null cropping is reset/removed.

Parameters:
Name Type Description
x Number
y Number
width Number
height Number
Source:

setFillViewer(fillViewer)

Sets the flag whether a fully zoomed-out view should fill the screen. If false, letterbox or side bars will be seen.

Parameters:
Name Type Description
fillViewer Boolean
Source:

setFullscreen(fullscreen)

Sets the flag whether the viewer should take over as full screen. Full screen also disables sleep mode on devices.

Parameters:
Name Type Description
fullscreen Boolean
Source:

setImageLocation(imageUrl)

Sets the IIIF image URL in the config.

Parameters:
Name Type Description
imageUrl String
Source:

setSequence(sequence)

Sets the supplied Pīwakawaka navigation sequence in the config.

Parameters:
Name Type Description
sequence Object
Source:

setSpeedFactor(speedFactor)

Sets the pan speed factor in the config.

Allows control of the pan speed by multiplying the specified factor over the base speed (10 pixels per second).

The speed is measured in 'webpage' pixels - so the speed appears consistent no matter what resolution the source image is or at what zoom level.

Higher is faster, e.g.

  • 1 = 10 px/sec
  • 5 = 50 px/sec
  • 20 = 200 px/sec
Parameters:
Name Type Description
speedFactor Number

Pan speed multiplier
Source:

stop()

Pauses automated sequence play. Can be resumed using resume().

Closes fullscreen display. Note that a long pan may continue running.

Source: