diff --git a/assets/logos/bbmri-logo.png b/assets/logos/bbmri-logo.png
new file mode 100644
index 00000000..8484d73f
Binary files /dev/null and b/assets/logos/bbmri-logo.png differ
diff --git a/changelog.txt b/changelog.txt
index 7635b993..b943536e 100644
--- a/changelog.txt
+++ b/changelog.txt
@@ -2,6 +2,28 @@ OPENSEADRAGON CHANGELOG
=======================
6.0.0: (in progress...)
+* NEW BEHAVIOR: OpenSeadragon Data Pipeline Overhaul
+ * DEPRECATION: Properties on tile that manage drawer data, or store data to draw: Tile.[element|imgElement|style|context2D|getImage|getCanvasContext] and transitively Tile.getScaleForEdgeSmoothing
+ * DEPRECATION: TileSource data lifecycle handlers: system manages these automatically: TileSource.[createTileCache|destroyTileCache|getTileCacheData|getTileCacheDataAsImage|getTileCacheDataAsContext2D]
+ * Tiles data is driven by caches: tiles can have multiple caches and cache can reference multiple tiles.
+ * Data types & conversion pipeline: caches support automated conversion between types, and call optionally destructors. These are asynchronous.
+ * Data conversion reasoning: the system keeps costs of convertors and seeks the cheapest conversion to a target format (using Dijkstra).
+ * Async support: events can now await handlers. Added OpenSeadragon.Promise proxy object. This object supports also synchronous mode.
+ * Drawers define what data they are able to work with, and receive automatically data from one of the declared types.
+ * Drawers now store data only inside cache, and provide optional type convertors to move data into a format they can work with.
+ * TileSource equality operator. TileSource destructor support. TileSources now must output type of the data they download [context.finish].
+ * Zombies: data can outlive tiles, and be kept in the system to wait if they are not suddenly needed. Turned on automatically with TiledImage addition with `replace: true` and equality test success.
+ * ImagesLoadedPerFrame is boosted 10 times when system is fresh (reset / open) and then declines back to original value.
+ * CacheRecord supports 'internal cache' of 'SimpleCache' type. This cache can be used by drawers to hide complex types used for rendering. Such caches are stored internally on CacheRecord objects.
+ * CacheRecord drives asynchronous data management and ensures correct behavior through awaiting Promises.
+ * TileCache adds new methods for cache modification: renameCache, cloneCache, injectCache, replaceCache, restoreTilesThatShareOriginalCache, safeUnloadCache, unloadCacheForTile and more. Used internally within invalidation events
+ * Tiles have up to two 'originalCacheKey' and 'cacheKey' caches, which keep original data and target drawn data (if modified).
+ * Invalidation Pipeline: New event 'tile-invalidated' and requestInvalidate methods on World and TiledImage. Tiles get methods to modify data to draw, system prepares data for drawing and swaps them with the current main tile cache.
+ * New test suites for the new cache system, conversion pipeline and invalidation events.
+ * New testing/demo utilities (MockSeadragon, DrawerSwitcher for switching drawers in demos, getBuiltInDrawersForTest for testing all drawers), serialization guard in tests to remove circular references.
+ * New demos, demonstrating the new pipeline. New demos for older plugins to show how compatible new version is.
+ * Misc: updated CSS for dev server, new dev & test commands.
+
5.0.1:
diff --git a/package.json b/package.json
index 7489ea2d..f858e5bc 100644
--- a/package.json
+++ b/package.json
@@ -46,6 +46,8 @@
},
"scripts": {
"test": "grunt test",
- "prepare": "grunt build"
+ "prepare": "grunt build",
+ "build": "grunt build",
+ "dev": "grunt dev"
}
}
diff --git a/src/canvasdrawer.js b/src/canvasdrawer.js
index e494d1f2..70d859dc 100644
--- a/src/canvasdrawer.js
+++ b/src/canvasdrawer.js
@@ -47,7 +47,7 @@
*/
class CanvasDrawer extends OpenSeadragon.DrawerBase{
- constructor(options){
+ constructor(options) {
super(options);
/**
@@ -69,7 +69,7 @@ class CanvasDrawer extends OpenSeadragon.DrawerBase{
* @memberof OpenSeadragon.CanvasDrawer#
* @private
*/
- this.context = this.canvas.getContext( '2d' );
+ this.context = this.canvas.getContext('2d');
// Sketch canvas used to temporarily draw tiles which cannot be drawn directly
// to the main canvas due to opacity. Lazily initialized.
@@ -97,6 +97,10 @@ class CanvasDrawer extends OpenSeadragon.DrawerBase{
return 'canvas';
}
+ getSupportedDataFormats() {
+ return ["context2d"];
+ }
+
/**
* create the HTML element (e.g. canvas, div) that the image will be drawn into
* @returns {Element} the canvas to draw into
@@ -267,26 +271,26 @@ class CanvasDrawer extends OpenSeadragon.DrawerBase{
*
*/
_drawTiles( tiledImage ) {
- var lastDrawn = tiledImage.getTilesToDraw().map(info => info.tile);
+ const lastDrawn = tiledImage.getTilesToDraw().map(info => info.tile);
if (tiledImage.opacity === 0 || (lastDrawn.length === 0 && !tiledImage.placeholderFillStyle)) {
return;
}
- var tile = lastDrawn[0];
- var useSketch;
+ let tile = lastDrawn[0];
+ let useSketch;
if (tile) {
useSketch = tiledImage.opacity < 1 ||
(tiledImage.compositeOperation && tiledImage.compositeOperation !== 'source-over') ||
(!tiledImage._isBottomItem() &&
- tiledImage.source.hasTransparency(tile.context2D, tile.getUrl(), tile.ajaxHeaders, tile.postData));
+ tiledImage.source.hasTransparency(null, tile.getUrl(), tile.ajaxHeaders, tile.postData));
}
- var sketchScale;
- var sketchTranslate;
+ let sketchScale;
+ let sketchTranslate;
- var zoom = this.viewport.getZoom(true);
- var imageZoom = tiledImage.viewportToImageZoom(zoom);
+ const zoom = this.viewport.getZoom(true);
+ const imageZoom = tiledImage.viewportToImageZoom(zoom);
if (lastDrawn.length > 1 &&
imageZoom > tiledImage.smoothTileEdgesMinZoom &&
@@ -296,13 +300,19 @@ class CanvasDrawer extends OpenSeadragon.DrawerBase{
// So we have to composite them at ~100% and scale them up together.
// Note: Disabled on iOS devices per default as it causes a native crash
useSketch = true;
- sketchScale = tile.getScaleForEdgeSmoothing();
+
+ const context = tile.length && this.getDataToDraw(tile);
+ if (context) {
+ sketchScale = context.canvas.width / (tile.size.x * $.pixelDensityRatio);
+ } else {
+ sketchScale = 1;
+ }
sketchTranslate = tile.getTranslationForEdgeSmoothing(sketchScale,
this._getCanvasSize(false),
this._getCanvasSize(true));
}
- var bounds;
+ let bounds;
if (useSketch) {
if (!sketchScale) {
// Except when edge smoothing, we only clean the part of the
@@ -322,13 +332,13 @@ class CanvasDrawer extends OpenSeadragon.DrawerBase{
this._setRotations(tiledImage, useSketch);
}
- var usedClip = false;
+ let usedClip = false;
if ( tiledImage._clip ) {
this._saveContext(useSketch);
- var box = tiledImage.imageToViewportRectangle(tiledImage._clip, true);
+ let box = tiledImage.imageToViewportRectangle(tiledImage._clip, true);
box = box.rotate(-tiledImage.getRotation(true), tiledImage._getRotationPoint(true));
- var clipRect = this.viewportToDrawerRectangle(box);
+ let clipRect = this.viewportToDrawerRectangle(box);
if (sketchScale) {
clipRect = clipRect.times(sketchScale);
}
@@ -341,17 +351,17 @@ class CanvasDrawer extends OpenSeadragon.DrawerBase{
}
if (tiledImage._croppingPolygons) {
- var self = this;
+ const self = this;
if(!usedClip){
this._saveContext(useSketch);
}
try {
- var polygons = tiledImage._croppingPolygons.map(function (polygon) {
+ const polygons = tiledImage._croppingPolygons.map(function (polygon) {
return polygon.map(function (coord) {
- var point = tiledImage
+ const point = tiledImage
.imageToViewportCoordinates(coord.x, coord.y, true)
.rotate(-tiledImage.getRotation(true), tiledImage._getRotationPoint(true));
- var clipPoint = self.viewportCoordToDrawerCoord(point);
+ let clipPoint = self.viewportCoordToDrawerCoord(point);
if (sketchScale) {
clipPoint = clipPoint.times(sketchScale);
}
@@ -388,19 +398,18 @@ class CanvasDrawer extends OpenSeadragon.DrawerBase{
this._drawRectangle(placeholderRect, fillStyle, useSketch);
}
- var subPixelRoundingRule = determineSubPixelRoundingRule(tiledImage.subPixelRoundingForTransparency);
+ const subPixelRoundingRule = determineSubPixelRoundingRule(tiledImage.subPixelRoundingForTransparency);
- var shouldRoundPositionAndSize = false;
+ let shouldRoundPositionAndSize = false;
if (subPixelRoundingRule === $.SUBPIXEL_ROUNDING_OCCURRENCES.ALWAYS) {
shouldRoundPositionAndSize = true;
} else if (subPixelRoundingRule === $.SUBPIXEL_ROUNDING_OCCURRENCES.ONLY_AT_REST) {
- var isAnimating = this.viewer && this.viewer.isAnimating();
- shouldRoundPositionAndSize = !isAnimating;
+ shouldRoundPositionAndSize = !(this.viewer && this.viewer.isAnimating());
}
// Iterate over the tiles to draw, and draw them
- for (var i = 0; i < lastDrawn.length; i++) {
+ for (let i = 0; i < lastDrawn.length; i++) {
tile = lastDrawn[ i ];
this._drawTile( tile, tiledImage, useSketch, sketchScale,
sketchTranslate, shouldRoundPositionAndSize, tiledImage.source );
@@ -462,9 +471,7 @@ class CanvasDrawer extends OpenSeadragon.DrawerBase{
this._drawDebugInfo( tiledImage, lastDrawn );
// Fire tiled-image-drawn event.
-
this._raiseTiledImageDrawnEvent(tiledImage, lastDrawn);
-
}
/**
@@ -522,52 +529,25 @@ class CanvasDrawer extends OpenSeadragon.DrawerBase{
$.console.assert(tile, '[Drawer._drawTile] tile is required');
$.console.assert(tiledImage, '[Drawer._drawTile] drawingHandler is required');
- var context = this._getContext(useSketch);
- scale = scale || 1;
- this._drawTileToCanvas(tile, context, tiledImage, scale, translate, shouldRoundPositionAndSize, source);
-
- }
-
- /**
- * Renders the tile in a canvas-based context.
- * @private
- * @function
- * @param {OpenSeadragon.Tile} tile - the tile to draw to the canvas
- * @param {Canvas} context
- * @param {OpenSeadragon.TiledImage} tiledImage - Method for firing the drawing event.
- * drawingHandler({context, tile, rendered})
- * where rendered is the context with the pre-drawn image.
- * @param {Number} [scale=1] - Apply a scale to position and size
- * @param {OpenSeadragon.Point} [translate] - A translation vector
- * @param {Boolean} [shouldRoundPositionAndSize] - Tells whether to round
- * position and size of tiles supporting alpha channel in non-transparency
- * context.
- * @param {OpenSeadragon.TileSource} source - The source specification of the tile.
- */
- _drawTileToCanvas( tile, context, tiledImage, scale, translate, shouldRoundPositionAndSize, source) {
-
- var position = tile.position.times($.pixelDensityRatio),
- size = tile.size.times($.pixelDensityRatio),
- rendered;
-
- if (!tile.context2D && !tile.cacheImageRecord) {
- $.console.warn(
- '[Drawer._drawTileToCanvas] attempting to draw tile %s when it\'s not cached',
- tile.toString());
- return;
- }
-
- rendered = tile.getCanvasContext();
-
- if ( !tile.loaded || !rendered ){
+ if ( !tile.loaded ){
$.console.warn(
"Attempting to draw tile %s when it's not yet loaded.",
tile.toString()
);
-
return;
}
+ const rendered = this.getDataToDraw(tile);
+ if (!rendered) {
+ return;
+ }
+
+ const context = this._getContext(useSketch);
+ scale = scale || 1;
+
+ let position = tile.position.times($.pixelDensityRatio),
+ size = tile.size.times($.pixelDensityRatio);
+
context.save();
if (typeof scale === 'number' && scale !== 1) {
@@ -606,7 +586,7 @@ class CanvasDrawer extends OpenSeadragon.DrawerBase{
this._raiseTileDrawingEvent(tiledImage, context, tile, rendered);
- var sourceWidth, sourceHeight;
+ let sourceWidth, sourceHeight;
if (tile.sourceBounds) {
sourceWidth = Math.min(tile.sourceBounds.width, rendered.canvas.width);
sourceHeight = Math.min(tile.sourceBounds.height, rendered.canvas.height);
@@ -634,6 +614,8 @@ class CanvasDrawer extends OpenSeadragon.DrawerBase{
context.restore();
}
+
+
/**
* Get the context of the main or sketch canvas
* @private
diff --git a/src/datatypeconvertor.js b/src/datatypeconvertor.js
new file mode 100644
index 00000000..ed6f0d8c
--- /dev/null
+++ b/src/datatypeconvertor.js
@@ -0,0 +1,488 @@
+/*
+ * OpenSeadragon.convertor (static property)
+ *
+ * Copyright (C) 2009 CodePlex Foundation
+ * Copyright (C) 2010-2024 OpenSeadragon contributors
+
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * - Redistributions of source code must retain the above copyright notice,
+ * this list of conditions and the following disclaimer.
+ *
+ * - Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ *
+ * - Neither the name of CodePlex Foundation nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+ * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+(function($){
+
+/**
+ * modified from https://gist.github.com/Prottoy2938/66849e04b0bac459606059f5f9f3aa1a
+ * @private
+ */
+class WeightedGraph {
+ constructor() {
+ this.adjacencyList = {};
+ this.vertices = {};
+ }
+
+ /**
+ * Add vertex to graph
+ * @param vertex unique vertex ID
+ * @return {boolean} true if inserted, false if exists (no-op)
+ */
+ addVertex(vertex) {
+ if (!this.vertices[vertex]) {
+ this.vertices[vertex] = new $.PriorityQueue.Node(0, vertex);
+ this.adjacencyList[vertex] = [];
+ return true;
+ }
+ return false;
+ }
+
+ /**
+ * Add edge to graph
+ * @param vertex1 id, must exist by calling addVertex()
+ * @param vertex2 id, must exist by calling addVertex()
+ * @param weight
+ * @param transform function that transforms on path vertex1 -> vertex2
+ * @return {boolean} true if new edge, false if replaced existing
+ */
+ addEdge(vertex1, vertex2, weight, transform) {
+ if (weight < 0) {
+ $.console.error("WeightedGraph: negative weights will make for invalid shortest path computation!");
+ }
+ const outgoingPaths = this.adjacencyList[vertex1],
+ replacedEdgeIndex = outgoingPaths.findIndex(edge => edge.target === this.vertices[vertex2]),
+ newEdge = { target: this.vertices[vertex2], origin: this.vertices[vertex1], weight, transform };
+ if (replacedEdgeIndex < 0) {
+ this.adjacencyList[vertex1].push(newEdge);
+ return true;
+ }
+ this.adjacencyList[vertex1][replacedEdgeIndex] = newEdge;
+ return false;
+ }
+
+ /**
+ * @return {{path: ConversionStep[], cost: number}|undefined} cheapest path from start to finish
+ */
+ dijkstra(start, finish) {
+ let path = []; //to return at end
+ if (start === finish) {
+ return {path: path, cost: 0};
+ }
+ const nodes = new OpenSeadragon.PriorityQueue();
+ let smallestNode;
+ //build up initial state
+ for (let vertex in this.vertices) {
+ vertex = this.vertices[vertex];
+ if (vertex.value === start) {
+ vertex.key = 0; //keys are known distances
+ nodes.insertNode(vertex);
+ } else {
+ vertex.key = Infinity;
+ delete vertex.index;
+ }
+ vertex._previous = null;
+ }
+ // as long as there is something to visit
+ while (nodes.getCount() > 0) {
+ smallestNode = nodes.remove();
+ if (smallestNode.value === finish) {
+ break;
+ }
+ const neighbors = this.adjacencyList[smallestNode.value];
+ for (let neighborKey in neighbors) {
+ let edge = neighbors[neighborKey];
+ //relax node
+ let newCost = smallestNode.key + edge.weight;
+ let nextNeighbor = edge.target;
+ if (newCost < nextNeighbor.key) {
+ nextNeighbor._previous = smallestNode;
+ //key change
+ nodes.decreaseKey(nextNeighbor, newCost);
+ }
+ }
+ }
+
+ if (!smallestNode || !smallestNode._previous || smallestNode.value !== finish) {
+ return undefined; //no path
+ }
+
+ let finalCost = smallestNode.key; //final weight last node
+
+ // done, build the shortest path
+ while (smallestNode._previous) {
+ //backtrack
+ const to = smallestNode.value,
+ parent = smallestNode._previous,
+ from = parent.value;
+
+ path.push(this.adjacencyList[from].find(x => x.target.value === to));
+ smallestNode = parent;
+ }
+
+ return {
+ path: path.reverse(),
+ cost: finalCost
+ };
+ }
+}
+
+/**
+ * Edge.transform function on the conversion path in OpenSeadragon.converter.getConversionPath().
+ * It can be also conversion to undefined if used as destructor implementation.
+ *
+ * @callback TypeConvertor
+ * @memberof OpenSeadragon
+ * @param {OpenSeadragon.Tile} tile reference tile that owns the data
+ * @param {any} data data in the input format
+ * @returns {any} data in the output format
+ */
+
+/**
+ * Destructor called every time a data type is to be destroyed or converted to another type.
+ *
+ * @callback TypeDestructor
+ * @memberof OpenSeadragon
+ * @param {any} data data in the format the destructor is registered for
+ * @returns {any} can return any value that is carried over to the caller if desirable.
+ * Note: not used by the OSD cache system.
+ */
+
+/**
+ * Node on the conversion path in OpenSeadragon.converter.getConversionPath().
+ *
+ * @typedef {Object} ConversionStep
+ * @memberof OpenSeadragon
+ * @param {OpenSeadragon.PriorityQueue.Node} target - Target node of the conversion step.
+ * Its value is the target format.
+ * @param {OpenSeadragon.PriorityQueue.Node} origin - Origin node of the conversion step.
+ * Its value is the origin format.
+ * @param {number} weight cost of the conversion
+ * @param {TypeConvertor} transform the conversion itself
+ */
+
+/**
+ * Class that orchestrates automated data types conversion. Do not instantiate
+ * this class, use OpenSeadragon.convertor - a global instance, instead.
+ * @class DataTypeConvertor
+ * @memberOf OpenSeadragon
+ */
+$.DataTypeConvertor = class {
+
+ constructor() {
+ this.graph = new WeightedGraph();
+ this.destructors = {};
+ this.copyings = {};
+
+ // Teaching OpenSeadragon built-in conversions:
+ const imageCreator = (tile, url) => new $.Promise((resolve, reject) => {
+ if (!$.supportsAsync) {
+ throw "Not supported in sync mode!";
+ }
+ const img = new Image();
+ img.onerror = img.onabort = reject;
+ img.onload = () => resolve(img);
+ img.src = url;
+ });
+ const canvasContextCreator = (tile, imageData) => {
+ const canvas = document.createElement( 'canvas' );
+ canvas.width = imageData.width;
+ canvas.height = imageData.height;
+ const context = canvas.getContext('2d', { willReadFrequently: true });
+ context.drawImage( imageData, 0, 0 );
+ return context;
+ };
+
+ this.learn("context2d", "webImageUrl", (tile, ctx) => ctx.canvas.toDataURL(), 1, 2);
+ this.learn("image", "webImageUrl", (tile, image) => image.url);
+ this.learn("image", "context2d", canvasContextCreator, 1, 1);
+ this.learn("url", "image", imageCreator, 1, 1);
+
+ //Copies
+ this.learn("image", "image", (tile, image) => imageCreator(tile, image.src), 1, 1);
+ this.learn("url", "url", (tile, url) => url, 0, 1); //strings are immutable, no need to copy
+ this.learn("context2d", "context2d", (tile, ctx) => canvasContextCreator(tile, ctx.canvas));
+
+ /**
+ * Free up canvas memory
+ * (iOS 12 or higher on 2GB RAM device has only 224MB canvas memory,
+ * and Safari keeps canvas until its height and width will be set to 0).
+ */
+ this.learnDestroy("context2d", ctx => {
+ ctx.canvas.width = 0;
+ ctx.canvas.height = 0;
+ });
+ }
+
+ /**
+ * Unique identifier (unlike toString.call(x)) to be guessed
+ * from the data value. This type guess is more strict than
+ * OpenSeadragon.type() implementation, but for most type recognition
+ * this test relies on the output of OpenSeadragon.type().
+ *
+ * Note: although we try to implement the type guessing, do
+ * not rely on this functionality! Prefer explicit type declaration.
+ *
+ * @function guessType
+ * @param x object to get unique identifier for
+ * - can be array, in that case, alphabetically-ordered list of inner unique types
+ * is returned (null, undefined are ignored)
+ * - if $.isPlainObject(x) is true, then the object can define
+ * getType function to specify its type
+ * - otherwise, toString.call(x) is applied to get the parameter description
+ * @return {string} unique variable descriptor
+ */
+ guessType( x ) {
+ if (Array.isArray(x)) {
+ const types = [];
+ for (let item of x) {
+ if (item === undefined || item === null) {
+ continue;
+ }
+
+ const type = this.guessType(item);
+ if (!types.includes(type)) {
+ types.push(type);
+ }
+ }
+ types.sort();
+ return `Array [${types.join(",")}]`;
+ }
+
+ const guessType = $.type(x);
+ if (guessType === "dom-node") {
+ //distinguish nodes
+ return guessType.nodeName.toLowerCase();
+ }
+
+ if (guessType === "object") {
+ if ($.isFunction(x.getType)) {
+ return x.getType();
+ }
+ }
+ return guessType;
+ }
+
+ /**
+ * Teach the system to convert data type 'from' -> 'to'
+ * @param {string} from unique ID of the data item 'from'
+ * @param {string} to unique ID of the data item 'to'
+ * @param {OpenSeadragon.TypeConvertor} callback convertor that takes two arguments: a tile reference, and
+ * a data object of a type 'from'; and converts this data object to type 'to'. It can return also the value
+ * wrapped in a Promise (returned in resolve) or it can be async function.
+ * @param {Number} [costPower=0] positive cost class of the conversion, smaller or equal than 7.
+ * Should reflect the actual cost of the conversion:
+ * - if nothing must be done and only reference is retrieved (or a constant operation done),
+ * return 0 (default)
+ * - if a linear amount of work is necessary,
+ * return 1
+ * ... and so on, basically the number in O() complexity power exponent (for simplification)
+ * @param {Number} [costMultiplier=1] multiplier of the cost class, e.g. O(3n^2) would
+ * use costPower=2, costMultiplier=3; can be between 1 and 10^5
+ */
+ learn(from, to, callback, costPower = 0, costMultiplier = 1) {
+ $.console.assert(costPower >= 0 && costPower <= 7, "[DataTypeConvertor] Conversion costPower must be between <0, 7>.");
+ $.console.assert($.isFunction(callback), "[DataTypeConvertor:learn] Callback must be a valid function!");
+
+ if (from === to) {
+ this.copyings[to] = callback;
+ } else {
+ //we won't know if somebody added multiple edges, though it will choose some edge anyway
+ costPower++;
+ costMultiplier = Math.min(Math.max(costMultiplier, 1), 10 ^ 5);
+ this.graph.addVertex(from);
+ this.graph.addVertex(to);
+ this.graph.addEdge(from, to, costPower * 10 ^ 5 + costMultiplier, callback);
+ this._known = {}; //invalidate precomputed paths :/
+ }
+ }
+
+ /**
+ * Teach the system to destroy data type 'type'
+ * for example, textures loaded to GPU have to be also manually removed when not needed anymore.
+ * Needs to be defined only when the created object has extra deletion process.
+ * @param {string} type
+ * @param {OpenSeadragon.TypeDestructor} callback destructor, receives the object created,
+ * it is basically a type conversion to 'undefined' - thus the type.
+ */
+ learnDestroy(type, callback) {
+ this.destructors[type] = callback;
+ }
+
+ /**
+ * Convert data item x of type 'from' to any of the 'to' types, chosen is the cheapest known conversion.
+ * Data is destroyed upon conversion. For different behavior, implement your conversion using the
+ * path rules obtained from getConversionPath().
+ * Note: conversion DOES NOT COPY data if [to] contains type 'from' (e.g., the cheapest conversion is no conversion).
+ * It automatically calls destructor on immediate types, but NOT on the x and the result. You should call these
+ * manually if these should be destroyed.
+ * @param {OpenSeadragon.Tile} tile
+ * @param {any} data data item to convert
+ * @param {string} from data item type
+ * @param {string} to desired type(s)
+ * @return {OpenSeadragon.Promise} promise resolution with type 'to' or undefined if the conversion failed
+ */
+ convert(tile, data, from, ...to) {
+ const conversionPath = this.getConversionPath(from, to);
+ if (!conversionPath) {
+ $.console.error(`[OpenSeadragon.convertor.convert] Conversion ${from} ---> ${to} cannot be done!`);
+ return $.Promise.resolve();
+ }
+
+ const stepCount = conversionPath.length,
+ _this = this;
+ const step = (x, i, destroy = true) => {
+ if (i >= stepCount) {
+ return $.Promise.resolve(x);
+ }
+ let edge = conversionPath[i];
+ let y = edge.transform(tile, x);
+ if (y === undefined) {
+ $.console.error(`[OpenSeadragon.convertor.convert] data mid result undefined value (while converting using %s)`, edge);
+ return $.Promise.resolve();
+ }
+ //node.value holds the type string
+ if (destroy) {
+ _this.destroy(x, edge.origin.value);
+ }
+ const result = $.type(y) === "promise" ? y : $.Promise.resolve(y);
+ return result.then(res => step(res, i + 1));
+ };
+ //destroy only mid-results, but not the original value
+ return step(data, 0, false);
+ }
+
+ /**
+ * Copy the data item given.
+ * @param {OpenSeadragon.Tile} tile
+ * @param {any} data data item to convert
+ * @param {string} type data type
+ * @return {OpenSeadragon.Promise|undefined} promise resolution with data passed from constructor
+ */
+ copy(tile, data, type) {
+ const copyTransform = this.copyings[type];
+ if (copyTransform) {
+ const y = copyTransform(tile, data);
+ return $.type(y) === "promise" ? y : $.Promise.resolve(y);
+ }
+ $.console.warn(`[OpenSeadragon.convertor.copy] is not supported with type %s`, type);
+ return $.Promise.resolve(undefined);
+ }
+
+ /**
+ * Destroy the data item given.
+ * @param {string} type data type
+ * @param {any} data
+ * @return {OpenSeadragon.Promise