+#############################################################################
+# Copyright Kitware Inc.
+#
+# Licensed under the Apache License, Version 2.0 ( the "License" );
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#############################################################################
+
+import hashlib
+import io
+import math
+import os
+import pathlib
+import pickle
+import re
+import urllib
+
+import cherrypy
+
+import large_image
+from girder.api import access, filter_logging
+from girder.api.describe import Description, autoDescribeRoute, describeRoute
+from girder.api.rest import filtermodel, loadmodel, setRawResponse, setResponseHeader
+from girder.api.v1.item import Item as ItemResource
+from girder.constants import AccessType, TokenScope
+from girder.exceptions import RestException
+from girder.models.file import File
+from girder.models.item import Item
+from girder.models.upload import Upload
+from girder.utility.progress import setResponseTimeLimit
+from large_image.cache_util import strhash
+from large_image.constants import TileInputUnits, TileOutputMimeTypes
+from large_image.exceptions import TileGeneralError
+
+from .. import loadmodelcache
+from ..models.image_item import ImageItem
+
+MimeTypeExtensions = {
+ 'image/jpeg': 'jpg',
+ 'image/png': 'png',
+ 'image/tiff': 'tiff',
+}
+for key, value in TileOutputMimeTypes.items():
+ if value not in MimeTypeExtensions:
+ MimeTypeExtensions[value] = key.lower()
+ImageMimeTypes = list(MimeTypeExtensions)
+EncodingTypes = list(TileOutputMimeTypes.keys()) + [
+ 'pickle', 'pickle:3', 'pickle:4', 'pickle:5']
+
+
+def _adjustParams(params):
+ """
+ Check the user agent of a request. If it appears to be from an iOS device,
+ and the request is asking for JPEG encoding (or hasn't specified an
+ encoding), then make sure the output is JFIF.
+
+ It is unfortunate that this requires analyzing the user agent, as this
+ method if brittle. However, other browsers can handle non-JFIF jpegs, and
+ we do not want to encur the overhead of conversion if it is not necessary
+ (converting to JFIF may require colorspace transforms).
+
+ :param params: the request parameters. May be modified.
+ """
+ try:
+ userAgent = cherrypy.request.headers.get('User-Agent', '').lower()
+ except Exception:
+ pass
+ if params.get('encoding', 'JPEG') == 'JPEG':
+ if ('ipad' in userAgent or 'ipod' in userAgent or 'iphone' in userAgent or
+ re.match('((?!chrome|android).)*safari', userAgent, re.IGNORECASE)):
+ params['encoding'] = 'JFIF'
+
+
+def _handleETag(key, item, *args, **kwargs):
+ """
+ Add or check an ETag header.
+
+ :param key: key for making a distinct etag.
+ :param item: item used for the item _id and updated timestamp.
+ :param max_age: the maximum cache duration.
+ :param *args, **kwargs: additional arguments for generating an etag.
+ """
+ max_age = kwargs.get('max_age', 3600)
+ id = str(item['_id'])
+ date = item.get('updated', item.get('created'))
+ etag = hashlib.md5(strhash(key, id, date, *args, **kwargs).encode()).hexdigest()
+ setResponseHeader('ETag', '"%s"' % etag)
+ conditions = [str(x) for x in cherrypy.request.headers.elements('If-Match') or []]
+ if conditions and not (conditions == ['*'] or etag in conditions):
+ raise cherrypy.HTTPError(
+ 412, 'If-Match failed: ETag %r did not match %r' % (etag, conditions))
+ conditions = [str(x).strip('"')
+ for x in cherrypy.request.headers.elements('If-None-Match') or []]
+ if conditions == ['*'] or etag in conditions:
+ raise cherrypy.HTTPRedirect([], 304)
+ # Explicitly set a max-age to recheck the cache after a while
+ setResponseHeader('Cache-control', f'public, max-age={max_age}')
+
+
+def _pickleParams(params):
+ """
+ Check if the output should be returned as pickled data and adjust the
+ parameters accordingly.
+
+ :param params: a dictionary of parameters. If encoding starts with
+ 'pickle', numpy format will be requested.
+ :return: None if the output should not be pickled. Otherwise, the pickle
+ protocol that should be used.
+ """
+ if not str(params.get('encoding')).startswith('pickle'):
+ return None
+ params['format'] = large_image.constants.TILE_FORMAT_NUMPY
+ pickle = params['encoding'].split(':')[-1]
+ del params['encoding']
+ return int(pickle) or 4 if pickle.isdigit() else 4
+
+
+def _pickleOutput(data, protocol):
+ """
+ Pickle some data using a specific protocol and return the pickled data
+ and the recommended mime type.
+
+ :param data: the data to pickle.
+ :param protocol: the pickle protocol level.
+ :returns: the pickled data and the mime type.
+ """
+ return (
+ pickle.dumps(data, protocol=min(protocol, pickle.HIGHEST_PROTOCOL)),
+ 'application/octet-stream')
+
+
+
+
[docs]
+
class TilesItemResource(ItemResource):
+
+
def __init__(self, apiRoot):
+
# Don't call the parent (Item) constructor, to avoid redefining routes,
+
# but do call the grandparent (Resource) constructor
+
super(ItemResource, self).__init__()
+
+
self.resourceName = 'item'
+
apiRoot.item.route('POST', (':itemId', 'tiles'), self.createTiles)
+
apiRoot.item.route('POST', (':itemId', 'tiles', 'convert'), self.convertImage)
+
apiRoot.item.route('GET', (':itemId', 'tiles'), self.getTilesInfo)
+
apiRoot.item.route('DELETE', (':itemId', 'tiles'), self.deleteTiles)
+
apiRoot.item.route('GET', (':itemId', 'tiles', 'thumbnail'), self.getTilesThumbnail)
+
apiRoot.item.route('GET', (':itemId', 'tiles', 'thumbnails'), self.listTilesThumbnails)
+
apiRoot.item.route('DELETE', (':itemId', 'tiles', 'thumbnails'), self.deleteTilesThumbnails)
+
apiRoot.item.route('POST', (':itemId', 'tiles', 'thumbnails'), self.addTilesThumbnails)
+
apiRoot.item.route('GET', (':itemId', 'tiles', 'region'), self.getTilesRegion)
+
apiRoot.item.route('GET', (':itemId', 'tiles', 'tile_frames'), self.tileFrames)
+
apiRoot.item.route('GET', (':itemId', 'tiles', 'tile_frames', 'quad_info'),
+
self.tileFramesQuadInfo)
+
apiRoot.item.route('GET', (':itemId', 'tiles', 'pixel'), self.getTilesPixel)
+
apiRoot.item.route('GET', (':itemId', 'tiles', 'histogram'), self.getHistogram)
+
apiRoot.item.route('GET', (':itemId', 'tiles', 'bands'), self.getBandInformation)
+
apiRoot.item.route('GET', (':itemId', 'tiles', 'zxy', ':z', ':x', ':y'), self.getTile)
+
apiRoot.item.route('GET', (':itemId', 'tiles', 'fzxy', ':frame', ':z', ':x', ':y'),
+
self.getTileWithFrame)
+
apiRoot.item.route('GET', (':itemId', 'tiles', 'images'), self.getAssociatedImagesList)
+
apiRoot.item.route('GET', (':itemId', 'tiles', 'images', ':image'),
+
self.getAssociatedImage)
+
apiRoot.item.route('GET', (':itemId', 'tiles', 'images', ':image', 'metadata'),
+
self.getAssociatedImageMetadata)
+
apiRoot.item.route('GET', ('test', 'tiles'), self.getTestTilesInfo)
+
apiRoot.item.route('GET', ('test', 'tiles', 'zxy', ':z', ':x', ':y'), self.getTestTile)
+
apiRoot.item.route('GET', (':itemId', 'tiles', 'dzi.dzi'), self.getDZIInfo)
+
apiRoot.item.route('GET', (':itemId', 'tiles', 'dzi_files', ':level', ':xandy'),
+
self.getDZITile)
+
apiRoot.item.route('GET', (':itemId', 'tiles', 'internal_metadata'),
+
self.getInternalMetadata)
+
# Logging rate limiters
+
filter_logging.addLoggingFilter(
+
'GET (/[^/ ?#]+)*/item/[^/ ?#]+/tiles/zxy(/[^/ ?#]+){3}',
+
frequency=250, duration=10)
+
filter_logging.addLoggingFilter(
+
'GET (/[^/ ?#]+)*/item/[^/ ?#]+/tiles/fzxy(/[^/ ?#]+){3}',
+
frequency=250, duration=10)
+
filter_logging.addLoggingFilter(
+
'GET (/[^/ ?#]+)*/item/[^/ ?#]+/tiles/dzi_files(/[^/ ?#]+){2}',
+
frequency=250, duration=10)
+
filter_logging.addLoggingFilter(
+
'GET (/[^/ ?#]+)*/item/[^/ ?#]+/tiles/region',
+
frequency=100, duration=10)
+
# Cache the model singleton
+
self.imageItemModel = ImageItem()
+
+
+
[docs]
+
@describeRoute(
+
Description('Create a large image for this item.')
+
.param('itemId', 'The source item.', paramType='path')
+
.param('fileId', 'The source file containing the image. Required if '
+
'there is more than one file in the item.', required=False)
+
.param('force', 'Always use a job to create the large image.',
+
dataType='boolean', default=False, required=False)
+
.param('notify', 'If a job is required to create the large image, '
+
'a nofication can be sent when it is complete.',
+
dataType='boolean', default=True, required=False)
+
.param('localJob', 'If true, run as a local job; if false, run via '
+
'the remote worker', dataType='boolean', required=False)
+
.param('tileSize', 'Tile size', dataType='int', default=256,
+
required=False)
+
.param('compression', 'Internal compression format', required=False,
+
enum=['none', 'jpeg', 'deflate', 'lzw', 'zstd', 'packbits', 'webp', 'jp2k'])
+
.param('quality', 'JPEG compression quality where 0 is small and 100 '
+
'is highest quality', dataType='int', default=90,
+
required=False)
+
.param('level', 'Compression level for deflate (zip) or zstd.',
+
dataType='int', required=False)
+
.param('predictor', 'Predictor for deflate (zip) or lzw.',
+
required=False, enum=['none', 'horizontal', 'float', 'yes'])
+
.param('psnr', 'JP2K compression target peak-signal-to-noise-ratio '
+
'where 0 is lossless and otherwise higher numbers are higher '
+
'quality', dataType='int', required=False)
+
.param('cr', 'JP2K target compression ratio where 1 is lossless',
+
dataType='int', required=False)
+
.param('concurrent', 'Suggested number of maximum concurrent '
+
'processes to use during conversion. Values less than or '
+
'equal to 0 use the number of logical cpus less that value. '
+
'Default is -2.', dataType='int', required=False),
+
)
+
@access.user(scope=TokenScope.DATA_WRITE)
+
@loadmodel(model='item', map={'itemId': 'item'}, level=AccessType.WRITE)
+
@filtermodel(model='job', plugin='jobs')
+
def createTiles(self, item, params):
+
if 'concurrent' in params:
+
params['_concurrency'] = params.pop('concurrent')
+
largeImageFileId = params.get('fileId')
+
if largeImageFileId is None:
+
files = list(Item().childFiles(item=item, limit=2))
+
if len(files) == 1:
+
largeImageFileId = str(files[0]['_id'])
+
if not largeImageFileId:
+
msg = 'Missing "fileId" parameter.'
+
raise RestException(msg)
+
largeImageFile = File().load(largeImageFileId, force=True, exc=True)
+
user = self.getCurrentUser()
+
token = self.getCurrentToken()
+
notify = self.boolParam('notify', params, default=True)
+
params.pop('notify', None)
+
localJob = self.boolParam('localJob', params, default=None)
+
params.pop('localJob', None)
+
try:
+
return self.imageItemModel.createImageItem(
+
item, largeImageFile, user, token,
+
createJob='always' if self.boolParam('force', params, default=False) else True,
+
notify=notify,
+
localJob=localJob,
+
**params)
+
except TileGeneralError as e:
+
raise RestException(e.args[0])
+
+
+
+
[docs]
+
@describeRoute(
+
Description('Create a new large image item based on an existing item')
+
.notes('This can be used to make an item that is a different internal '
+
'format than the original item.')
+
.param('itemId', 'The source item.', paramType='path')
+
.param('fileId', 'The source file containing the image. Required if '
+
'there is more than one file in the item.', required=False)
+
.param('folderId', 'The destination folder.', required=False)
+
.param('name', 'A new name for the output item.', required=False)
+
.param('localJob', 'If true, run as a local job; if false, run via '
+
'the remote worker', dataType='boolean', required=False)
+
.param('tileSize', 'Tile size', dataType='int', default=256,
+
required=False)
+
.param('onlyFrame', 'Only convert a specific 0-based frame of a '
+
'multiframe file. If not specified, all frames are converted.',
+
dataType='int', required=False)
+
.param('format', 'File format', required=False,
+
enum=['tiff', 'aperio'])
+
.param('compression', 'Internal compression format', required=False,
+
enum=['none', 'jpeg', 'deflate', 'lzw', 'zstd', 'packbits', 'webp', 'jp2k'])
+
.param('quality', 'JPEG compression quality where 0 is small and 100 '
+
'is highest quality', dataType='int', default=90,
+
required=False)
+
.param('level', 'Compression level for deflate (zip) or zstd.',
+
dataType='int', required=False)
+
.param('predictor', 'Predictor for deflate (zip) or lzw.',
+
required=False, enum=['none', 'horizontal', 'float', 'yes'])
+
.param('psnr', 'JP2K compression target peak-signal-to-noise-ratio '
+
'where 0 is lossless and otherwise higher numbers are higher '
+
'quality', dataType='int', required=False)
+
.param('cr', 'JP2K target compression ratio where 1 is lossless',
+
dataType='int', required=False)
+
.param('concurrent', 'Suggested number of maximum concurrent '
+
'processes to use during conversion. Values less than or '
+
'equal to 0 use the number of logical cpus less that value. '
+
'Default is -2.', dataType='int', required=False),
+
)
+
@access.user(scope=TokenScope.DATA_WRITE)
+
@loadmodel(model='item', map={'itemId': 'item'}, level=AccessType.READ)
+
@filtermodel(model='job', plugin='jobs')
+
def convertImage(self, item, params):
+
if 'concurrent' in params:
+
params['_concurrency'] = params.pop('concurrent')
+
largeImageFileId = params.get('fileId')
+
if largeImageFileId is None:
+
files = list(Item().childFiles(item=item, limit=2))
+
if len(files) == 1:
+
largeImageFileId = str(files[0]['_id'])
+
if not largeImageFileId:
+
msg = 'Missing "fileId" parameter.'
+
raise RestException(msg)
+
largeImageFile = File().load(largeImageFileId, force=True, exc=True)
+
user = self.getCurrentUser()
+
token = self.getCurrentToken()
+
params.pop('notify', None)
+
localJob = self.boolParam('localJob', params, default=True)
+
params.pop('localJob', None)
+
try:
+
return self.imageItemModel.convertImage(
+
item, largeImageFile, user, token, localJob=localJob, **params)
+
except TileGeneralError as e:
+
raise RestException(e.args[0])
+
+
+
@classmethod
+
def _parseTestParams(cls, params):
+
_adjustParams(params)
+
return cls._parseParams(params, False, [
+
('minLevel', int),
+
('maxLevel', int),
+
('tileWidth', int),
+
('tileHeight', int),
+
('sizeX', int),
+
('sizeY', int),
+
('fractal', lambda val: val == 'true'),
+
('frame', int),
+
('frames', str),
+
('monochrome', lambda val: val == 'true'),
+
('encoding', str),
+
])
+
+
@classmethod
+
def _parseParams(cls, params, keepUnknownParams, typeList):
+
"""
+
Given a dictionary of parameters, check that a list of parameters are
+
valid data types. The parameters within the list are validated and
+
copied to a dictionary by themselves.
+
+
:param params: the dictionary of parameters to validate.
+
:param keepUnknownParams: True to copy all parameters, not just those
+
in the typeList. The parameters in the typeList are still
+
validated.
+
:param typeList: a list of tuples of the form (key, dataType, [outkey1,
+
[outkey2]]). If output keys are used, the original key is renamed
+
to the the output key. If two output keys are specified, the
+
original key is renamed to outkey2 and placed in a sub-dictionary
+
names outkey1.
+
:returns: params: a validated and possibly filtered list of parameters.
+
"""
+
results = {}
+
if keepUnknownParams:
+
results = dict(params)
+
for entry in typeList:
+
key, dataType, outkey1, outkey2 = (list(entry) + [None] * 2)[:4]
+
if key in params:
+
if dataType == 'boolOrInt':
+
dataType = bool if str(params[key]).lower() in (
+
'true', 'false', 'on', 'off', 'yes', 'no') else int
+
try:
+
if dataType is bool:
+
results[key] = str(params[key]).lower() in (
+
'true', 'on', 'yes', '1')
+
else:
+
results[key] = dataType(params[key])
+
except ValueError:
+
raise RestException(
+
'"%s" parameter is an incorrect type.' % key)
+
if outkey1 is not None:
+
if outkey2 is not None:
+
results.setdefault(outkey1, {})[outkey2] = results[key]
+
else:
+
results[outkey1] = results[key]
+
del results[key]
+
return results
+
+
def _getTilesInfo(self, item, imageArgs):
+
"""
+
Get metadata for an item's large image.
+
+
:param item: the item to query.
+
:param imageArgs: additional arguments to use when fetching image data.
+
:return: the tile metadata.
+
"""
+
try:
+
return self.imageItemModel.getMetadata(item, **imageArgs)
+
except TileGeneralError as e:
+
raise RestException(e.args[0], code=400)
+
+
def _setContentDisposition(self, item, contentDisposition, mime, subname, fullFilename=None):
+
"""
+
If requested, set the content disposition and a suggested file name.
+
+
:param item: an item that includes a name.
+
:param contentDisposition: either 'inline' or 'attachment', otherwise
+
no header is added.
+
:param mime: the mimetype of the output image. Used for the filename
+
suffix.
+
:param subname: a subname to append to the item name.
+
:param fullFilename: if specified, use this instead of the item name
+
and the subname.
+
"""
+
if (not item or not item.get('name') or
+
mime not in MimeTypeExtensions or
+
contentDisposition not in ('inline', 'attachment')):
+
return
+
if fullFilename:
+
filename = fullFilename
+
else:
+
filename = os.path.splitext(item['name'])[0]
+
if subname:
+
filename += '-' + subname
+
filename += '.' + MimeTypeExtensions[mime]
+
if not isinstance(filename, str):
+
filename = filename.decode('utf8', 'ignore')
+
safeFilename = filename.encode('ascii', 'ignore').replace(b'"', b'')
+
encodedFilename = urllib.parse.quote(filename.encode('utf8', 'ignore'))
+
setResponseHeader(
+
'Content-Disposition',
+
'%s; filename="%s"; filename*=UTF-8\'\'%s' % (
+
contentDisposition, safeFilename, encodedFilename))
+
+
+
[docs]
+
@describeRoute(
+
Description('Get large image metadata.')
+
.param('itemId', 'The ID of the item.', paramType='path')
+
.errorResponse('ID was invalid.')
+
.errorResponse('Read access was denied for the item.', 403),
+
)
+
@access.public(scope=TokenScope.DATA_READ)
+
@loadmodel(model='item', map={'itemId': 'item'}, level=AccessType.READ)
+
def getTilesInfo(self, item, params):
+
return self._getTilesInfo(item, params)
+
+
+
+
+
+
+
[docs]
+
@describeRoute(
+
Description('Get test large image metadata.'),
+
)
+
@access.public(scope=TokenScope.DATA_READ)
+
def getTestTilesInfo(self, params):
+
item = {'largeImage': {'sourceName': 'test'}}
+
imageArgs = self._parseTestParams(params)
+
return self._getTilesInfo(item, imageArgs)
+
+
+
+
[docs]
+
@describeRoute(
+
Description('Get DeepZoom compatible metadata.')
+
.param('itemId', 'The ID of the item.', paramType='path')
+
.param('overlap', 'Pixel overlap (default 0), must be non-negative.',
+
required=False, dataType='int')
+
.param('tilesize', 'Tile size (default 256), must be a power of 2',
+
required=False, dataType='int')
+
.errorResponse('ID was invalid.')
+
.errorResponse('Read access was denied for the item.', 403),
+
)
+
@access.public(scope=TokenScope.DATA_READ)
+
@loadmodel(model='item', map={'itemId': 'item'}, level=AccessType.READ)
+
def getDZIInfo(self, item, params):
+
if 'encoding' in params and params['encoding'] not in ('JPEG', 'PNG'):
+
msg = 'Only JPEG and PNG encodings are supported'
+
raise RestException(msg, code=400)
+
info = self._getTilesInfo(item, params)
+
tilesize = int(params.get('tilesize', 256))
+
if tilesize & (tilesize - 1):
+
msg = 'Invalid tilesize'
+
raise RestException(msg, code=400)
+
overlap = int(params.get('overlap', 0))
+
if overlap < 0:
+
msg = 'Invalid overlap'
+
raise RestException(msg, code=400)
+
result = ''.join([
+
'<?xml version="1.0" encoding="UTF-8"?>',
+
'<Image',
+
' TileSize="%d"' % tilesize,
+
' Overlap="%d"' % overlap,
+
' Format="%s"' % ('png' if params.get('encoding') == 'PNG' else 'jpg'),
+
' xmlns="http://schemas.microsoft.com/deepzoom/2008">',
+
'<Size',
+
' Width="%d"' % info['sizeX'],
+
' Height="%d"' % info['sizeY'],
+
'/>'
+
'</Image>',
+
])
+
setResponseHeader('Content-Type', 'text/xml')
+
setRawResponse()
+
return result
+
+
+
def _getTile(self, item, z, x, y, imageArgs, mayRedirect=False):
+
"""
+
Get an large image tile.
+
+
:param item: the item to get a tile from.
+
:param z: tile layer number (0 is the most zoomed-out).
+
.param x: the X coordinate of the tile (0 is the left side).
+
.param y: the Y coordinate of the tile (0 is the top).
+
:param imageArgs: additional arguments to use when fetching image data.
+
:param mayRedirect: if True or one of 'any', 'encoding', or 'exact',
+
allow return a response which may be a redirect.
+
:return: a function that returns the raw image data.
+
"""
+
try:
+
x, y, z = int(x), int(y), int(z)
+
except ValueError:
+
msg = 'x, y, and z must be integers'
+
raise RestException(msg, code=400)
+
if x < 0 or y < 0 or z < 0:
+
msg = 'x, y, and z must be positive integers'
+
raise RestException(msg,
+
code=400)
+
result = self.imageItemModel._tileFromHash(
+
item, x, y, z, mayRedirect=mayRedirect, **imageArgs)
+
if result is not None:
+
tileData, tileMime = result
+
else:
+
try:
+
tileData, tileMime = self.imageItemModel.getTile(
+
item, x, y, z, mayRedirect=mayRedirect, **imageArgs)
+
except TileGeneralError as e:
+
raise RestException(e.args[0], code=404)
+
setResponseHeader('Content-Type', tileMime)
+
setRawResponse()
+
return tileData
+
+
+
[docs]
+
@describeRoute(
+
Description('Get a large image tile.')
+
.param('itemId', 'The ID of the item.', paramType='path')
+
.param('z', 'The layer number of the tile (0 is the most zoomed-out '
+
'layer).', paramType='path')
+
.param('x', 'The X coordinate of the tile (0 is the left side).',
+
paramType='path')
+
.param('y', 'The Y coordinate of the tile (0 is the top).',
+
paramType='path')
+
.param('redirect', 'If the tile exists as a complete file, allow an '
+
'HTTP redirect instead of returning the data directly. The '
+
'redirect might not have the correct mime type. "exact" must '
+
'match the image encoding and quality parameters, "encoding" '
+
'must match the image encoding but disregards quality, and '
+
'"any" will redirect to any image if possible.', required=False,
+
enum=['false', 'exact', 'encoding', 'any'], default='false')
+
.produces(ImageMimeTypes)
+
.errorResponse('ID was invalid.')
+
.errorResponse('Read access was denied for the item.', 403),
+
)
+
# Without caching, this checks for permissions every time. By using the
+
# LoadModelCache, three database lookups are avoided, which saves around
+
# 6 ms in tests. We also avoid the @access.public decorator and directly
+
# set the accessLevel attribute on the method.
+
# @access.public(cookie=True, scope=TokenScope.DATA_READ)
+
# @loadmodel(model='item', map={'itemId': 'item'}, level=AccessType.READ)
+
# def getTile(self, item, z, x, y, params):
+
# return self._getTile(item, z, x, y, params, True)
+
def getTile(self, itemId, z, x, y, params):
+
_adjustParams(params)
+
item = loadmodelcache.loadModel(
+
self, 'item', id=itemId, allowCookie=True, level=AccessType.READ)
+
_handleETag('getTile', item, z, x, y, params)
+
redirect = params.get('redirect', False)
+
if redirect not in ('any', 'exact', 'encoding'):
+
redirect = False
+
return self._getTile(item, z, x, y, params, mayRedirect=redirect)
+
+
getTile.accessLevel = 'public'
+
getTile.cookieAuth = True
+
getTile.requiredScopes = TokenScope.DATA_READ
+
+
+
[docs]
+
@describeRoute(
+
Description('Get a large image tile with a frame number.')
+
.param('itemId', 'The ID of the item.', paramType='path')
+
.param('frame', 'The frame number of the tile.', paramType='path')
+
.param('z', 'The layer number of the tile (0 is the most zoomed-out '
+
'layer).', paramType='path')
+
.param('x', 'The X coordinate of the tile (0 is the left side).',
+
paramType='path')
+
.param('y', 'The Y coordinate of the tile (0 is the top).',
+
paramType='path')
+
.param('redirect', 'If the tile exists as a complete file, allow an '
+
'HTTP redirect instead of returning the data directly. The '
+
'redirect might not have the correct mime type. "exact" must '
+
'match the image encoding and quality parameters, "encoding" '
+
'must match the image encoding but disregards quality, and '
+
'"any" will redirect to any image if possible.', required=False,
+
enum=['false', 'exact', 'encoding', 'any'], default='false')
+
.produces(ImageMimeTypes)
+
.errorResponse('ID was invalid.')
+
.errorResponse('Read access was denied for the item.', 403),
+
)
+
# See getTile for caching rationale
+
def getTileWithFrame(self, itemId, frame, z, x, y, params):
+
_adjustParams(params)
+
item = loadmodelcache.loadModel(
+
self, 'item', id=itemId, allowCookie=True, level=AccessType.READ)
+
_handleETag('getTileWithFrame', item, frame, z, x, y, params)
+
redirect = params.get('redirect', False)
+
if redirect not in ('any', 'exact', 'encoding'):
+
redirect = False
+
params['frame'] = frame
+
return self._getTile(item, z, x, y, params, mayRedirect=redirect)
+
+
getTileWithFrame.accessLevel = 'public'
+
+
+
[docs]
+
@describeRoute(
+
Description('Get a test large image tile.')
+
.param('z', 'The layer number of the tile (0 is the most zoomed-out '
+
'layer).', paramType='path')
+
.param('x', 'The X coordinate of the tile (0 is the left side).',
+
paramType='path')
+
.param('y', 'The Y coordinate of the tile (0 is the top).',
+
paramType='path')
+
.produces(ImageMimeTypes),
+
)
+
@access.public(cookie=True, scope=TokenScope.DATA_READ)
+
def getTestTile(self, z, x, y, params):
+
item = {'largeImage': {'sourceName': 'test'}}
+
imageArgs = self._parseTestParams(params)
+
return self._getTile(item, z, x, y, imageArgs)
+
+
+
+
[docs]
+
@describeRoute(
+
Description('Get a DeepZoom image tile.')
+
.param('itemId', 'The ID of the item.', paramType='path')
+
.param('level', 'The deepzoom layer number of the tile (8 is the '
+
'most zoomed-out layer).', paramType='path')
+
.param('xandy', 'The X and Y coordinate of the tile in the form '
+
'(x)_(y).(extension) where (0_0 is the left top).',
+
paramType='path')
+
.produces(ImageMimeTypes)
+
.errorResponse('ID was invalid.')
+
.errorResponse('Read access was denied for the item.', 403),
+
)
+
@access.public(cookie=True, scope=TokenScope.DATA_READ)
+
@loadmodel(model='item', map={'itemId': 'item'}, level=AccessType.READ)
+
def getDZITile(self, item, level, xandy, params):
+
_adjustParams(params)
+
tilesize = int(params.get('tilesize', 256))
+
if tilesize & (tilesize - 1):
+
msg = 'Invalid tilesize'
+
raise RestException(msg, code=400)
+
overlap = int(params.get('overlap', 0))
+
if overlap < 0:
+
msg = 'Invalid overlap'
+
raise RestException(msg, code=400)
+
x, y = (int(xy) for xy in xandy.split('.')[0].split('_'))
+
_handleETag('getDZITile', item, level, xandy, params)
+
metadata = self.imageItemModel.getMetadata(item, **params)
+
level = int(level)
+
maxlevel = int(math.ceil(math.log(max(
+
metadata['sizeX'], metadata['sizeY'])) / math.log(2)))
+
if level < 1 or level > maxlevel:
+
msg = 'level must be between 1 and the image scale'
+
raise RestException(msg,
+
code=400)
+
lfactor = 2 ** (maxlevel - level)
+
region = {
+
'left': (x * tilesize - overlap) * lfactor,
+
'top': (y * tilesize - overlap) * lfactor,
+
'right': ((x + 1) * tilesize + overlap) * lfactor,
+
'bottom': ((y + 1) * tilesize + overlap) * lfactor,
+
}
+
width = height = tilesize + overlap * 2
+
if region['left'] < 0:
+
width += int(region['left'] / lfactor)
+
region['left'] = 0
+
if region['top'] < 0:
+
height += int(region['top'] / lfactor)
+
region['top'] = 0
+
if region['left'] >= metadata['sizeX']:
+
msg = 'x is outside layer'
+
raise RestException(msg, code=400)
+
if region['top'] >= metadata['sizeY']:
+
msg = 'y is outside layer'
+
raise RestException(msg, code=400)
+
if region['left'] < metadata['sizeX'] and region['right'] > metadata['sizeX']:
+
region['right'] = metadata['sizeX']
+
width = int(math.ceil(float(region['right'] - region['left']) / lfactor))
+
if region['top'] < metadata['sizeY'] and region['bottom'] > metadata['sizeY']:
+
region['bottom'] = metadata['sizeY']
+
height = int(math.ceil(float(region['bottom'] - region['top']) / lfactor))
+
regionData, regionMime = self.imageItemModel.getRegion(
+
item,
+
region=region,
+
output=dict(maxWidth=width, maxHeight=height),
+
**params)
+
setResponseHeader('Content-Type', regionMime)
+
setRawResponse()
+
return regionData
+
+
+
+
[docs]
+
@describeRoute(
+
Description('Remove a large image from this item.')
+
.param('itemId', 'The ID of the item.', paramType='path'),
+
)
+
@access.user(scope=TokenScope.DATA_WRITE)
+
@loadmodel(model='item', map={'itemId': 'item'}, level=AccessType.WRITE)
+
def deleteTiles(self, item, params):
+
deleted = self.imageItemModel.delete(item)
+
return {
+
'deleted': deleted,
+
}
+
+
+
+
[docs]
+
@describeRoute(
+
Description('Get a thumbnail of a large image item.')
+
.notes('Aspect ratio is always preserved. If both width and height '
+
'are specified, the resulting thumbnail may be smaller in one '
+
'of the two dimensions. If neither width nor height is given, '
+
'a default size will be returned. '
+
'This creates a thumbnail from the lowest level of the source '
+
'image, which means that asking for a large thumbnail will not '
+
'be a high-quality image.')
+
.param('itemId', 'The ID of the item.', paramType='path')
+
.param('width', 'The maximum width of the thumbnail in pixels.',
+
required=False, dataType='int')
+
.param('height', 'The maximum height of the thumbnail in pixels.',
+
required=False, dataType='int')
+
.param('fill', 'A fill color. If width and height are both specified '
+
'and fill is specified and not "none", the output image is '
+
'padded on either the sides or the top and bottom to the '
+
'requested output size. Most css colors are accepted.',
+
required=False)
+
.param('frame', 'For multiframe images, the 0-based frame number. '
+
'This is ignored on non-multiframe images.', required=False,
+
dataType='int')
+
.param('encoding', 'Output image encoding. TILED generates a tiled '
+
'tiff without the upper limit on image size the other options '
+
'have. For geospatial sources, TILED will also have '
+
'appropriate tagging. Pickle emits python pickle data with an '
+
'optional specific protocol', required=False,
+
enum=EncodingTypes, default='JPEG')
+
.param('contentDisposition', 'Specify the Content-Disposition response '
+
'header disposition-type value.', required=False,
+
enum=['inline', 'attachment'])
+
.param('contentDispositionFilename', 'Specify the filename used in '
+
'the Content-Disposition response header.', required=False)
+
.produces(ImageMimeTypes)
+
.errorResponse('ID was invalid.')
+
.errorResponse('Read access was denied for the item.', 403),
+
)
+
@access.public(cookie=True, scope=TokenScope.DATA_READ)
+
@loadmodel(model='item', map={'itemId': 'item'}, level=AccessType.READ)
+
def getTilesThumbnail(self, item, params):
+
_adjustParams(params)
+
params = self._parseParams(params, True, [
+
('width', int),
+
('height', int),
+
('fill', str),
+
('frame', int),
+
('jpegQuality', int),
+
('jpegSubsampling', int),
+
('tiffCompression', str),
+
('encoding', str),
+
('style', str),
+
('contentDisposition', str),
+
('contentDispositionFileName', str),
+
])
+
_handleETag('getTilesThumbnail', item, params)
+
pickle = _pickleParams(params)
+
try:
+
result = self.imageItemModel.getThumbnail(item, **params)
+
except TileGeneralError as e:
+
raise RestException(e.args[0])
+
except ValueError as e:
+
raise RestException('Value Error: %s' % e.args[0])
+
if not isinstance(result, tuple):
+
return result
+
thumbData, thumbMime = result
+
if pickle:
+
thumbData, thumbMime = _pickleOutput(thumbData, pickle)
+
self._setContentDisposition(
+
item, params.get('contentDisposition'), thumbMime, 'thumbnail',
+
params.get('contentDispositionFilename'))
+
setResponseHeader('Content-Type', thumbMime)
+
setRawResponse()
+
return thumbData
+
+
+
+
[docs]
+
@describeRoute(
+
Description('Get any region of a large image item, optionally scaling '
+
'it.')
+
.notes('If neither width nor height is specified, the full resolution '
+
'region is returned. If a width or height is specified, '
+
'aspect ratio is always preserved (if both are given, the '
+
'resulting image may be smaller in one of the two '
+
'dimensions). When scaling must be applied, the image is '
+
'downsampled from a higher resolution layer, never upsampled.')
+
.param('itemId', 'The ID of the item.', paramType='path')
+
.param('left', 'The left column (0-based) of the region to process. '
+
'Negative values are offsets from the right edge.',
+
required=False, dataType='float')
+
.param('top', 'The top row (0-based) of the region to process. '
+
'Negative values are offsets from the bottom edge.',
+
required=False, dataType='float')
+
.param('right', 'The right column (0-based from the left) of the '
+
'region to process. The region will not include this column. '
+
'Negative values are offsets from the right edge.',
+
required=False, dataType='float')
+
.param('bottom', 'The bottom row (0-based from the top) of the region '
+
'to process. The region will not include this row. Negative '
+
'values are offsets from the bottom edge.',
+
required=False, dataType='float')
+
.param('regionWidth', 'The width of the region to process.',
+
required=False, dataType='float')
+
.param('regionHeight', 'The height of the region to process.',
+
required=False, dataType='float')
+
.param('units', 'Units used for left, top, right, bottom, '
+
'regionWidth, and regionHeight. base_pixels are pixels at the '
+
'maximum resolution, pixels and mm are at the specified '
+
'magnfication, fraction is a scale of [0-1].', required=False,
+
enum=sorted(set(TileInputUnits.values())),
+
default='base_pixels')
+
+
.param('width', 'The maximum width of the output image in pixels.',
+
required=False, dataType='int')
+
.param('height', 'The maximum height of the output image in pixels.',
+
required=False, dataType='int')
+
.param('fill', 'A fill color. If output dimensions are specified and '
+
'fill is specified and not "none", the output image is padded '
+
'on either the sides or the top and bottom to the requested '
+
'output size. Most css colors are accepted.', required=False)
+
.param('magnification', 'Magnification of the output image. If '
+
'neither width for height is specified, the magnification, '
+
'mm_x, and mm_y parameters are used to select the output size.',
+
required=False, dataType='float')
+
.param('mm_x', 'The size of the output pixels in millimeters',
+
required=False, dataType='float')
+
.param('mm_y', 'The size of the output pixels in millimeters',
+
required=False, dataType='float')
+
.param('exact', 'If magnification, mm_x, or mm_y are specified, they '
+
'must match an existing level of the image exactly.',
+
required=False, dataType='boolean', default=False)
+
.param('frame', 'For multiframe images, the 0-based frame number. '
+
'This is ignored on non-multiframe images.', required=False,
+
dataType='int')
+
.param('encoding', 'Output image encoding. TILED generates a tiled '
+
'tiff without the upper limit on image size the other options '
+
'have. For geospatial sources, TILED will also have '
+
'appropriate tagging. Pickle emits python pickle data with an '
+
'optional specific protocol', required=False,
+
enum=EncodingTypes, default='JPEG')
+
.param('jpegQuality', 'Quality used for generating JPEG images',
+
required=False, dataType='int', default=95)
+
.param('jpegSubsampling', 'Chroma subsampling used for generating '
+
'JPEG images. 0, 1, and 2 are full, half, and quarter '
+
'resolution chroma respectively.', required=False,
+
enum=['0', '1', '2'], dataType='int', default='0')
+
.param('tiffCompression', 'Compression method when storing a TIFF '
+
'image', required=False,
+
enum=['none', 'raw', 'lzw', 'tiff_lzw', 'jpeg', 'deflate',
+
'tiff_adobe_deflate'])
+
.param('style', 'JSON-encoded style string', required=False)
+
.param('resample', 'If false, an existing level of the image is used '
+
'for the region. If true, the internal values are '
+
'interpolated to match the specified size as needed. 0-3 for '
+
'a specific interpolation method (0-nearest, 1-lanczos, '
+
'2-bilinear, 3-bicubic)', required=False,
+
enum=['false', 'true', '0', '1', '2', '3'])
+
.param('contentDisposition', 'Specify the Content-Disposition response '
+
'header disposition-type value.', required=False,
+
enum=['inline', 'attachment'])
+
.param('contentDispositionFilename', 'Specify the filename used in '
+
'the Content-Disposition response header.', required=False)
+
.produces(ImageMimeTypes)
+
.errorResponse('ID was invalid.')
+
.errorResponse('Read access was denied for the item.', 403)
+
.errorResponse('Insufficient memory.'),
+
)
+
@access.public(cookie=True, scope=TokenScope.DATA_READ)
+
@loadmodel(model='item', map={'itemId': 'item'}, level=AccessType.READ)
+
def getTilesRegion(self, item, params):
+
_adjustParams(params)
+
params = self._parseParams(params, True, [
+
('left', float, 'region', 'left'),
+
('top', float, 'region', 'top'),
+
('right', float, 'region', 'right'),
+
('bottom', float, 'region', 'bottom'),
+
('regionWidth', float, 'region', 'width'),
+
('regionHeight', float, 'region', 'height'),
+
('units', str, 'region', 'units'),
+
('unitsWH', str, 'region', 'unitsWH'),
+
('width', int, 'output', 'maxWidth'),
+
('height', int, 'output', 'maxHeight'),
+
('fill', str),
+
('magnification', float, 'scale', 'magnification'),
+
('mm_x', float, 'scale', 'mm_x'),
+
('mm_y', float, 'scale', 'mm_y'),
+
('exact', bool, 'scale', 'exact'),
+
('frame', int),
+
('encoding', str),
+
('jpegQuality', int),
+
('jpegSubsampling', int),
+
('tiffCompression', str),
+
('style', str),
+
('resample', 'boolOrInt'),
+
('contentDisposition', str),
+
('contentDispositionFileName', str),
+
])
+
_handleETag('getTilesRegion', item, params)
+
pickle = _pickleParams(params)
+
setResponseTimeLimit(86400)
+
try:
+
regionData, regionMime = self.imageItemModel.getRegion(
+
item, **params)
+
if pickle:
+
regionData, regionMime = _pickleOutput(regionData, pickle)
+
except TileGeneralError as e:
+
raise RestException(e.args[0])
+
except ValueError as e:
+
raise RestException('Value Error: %s' % e.args[0])
+
self._setContentDisposition(
+
item, params.get('contentDisposition'), regionMime, 'region',
+
params.get('contentDispositionFilename'))
+
setResponseHeader('Content-Type', regionMime)
+
if isinstance(regionData, pathlib.Path):
+
BUF_SIZE = 65536
+
+
def stream():
+
try:
+
with regionData.open('rb') as f:
+
while True:
+
data = f.read(BUF_SIZE)
+
if not data:
+
break
+
yield data
+
finally:
+
regionData.unlink()
+
return stream
+
setRawResponse()
+
return regionData
+
+
+
+
[docs]
+
@describeRoute(
+
Description('Get a single pixel of a large image item.')
+
.param('itemId', 'The ID of the item.', paramType='path')
+
.param('left', 'The left column (0-based) of the pixel.',
+
required=False, dataType='float')
+
.param('top', 'The top row (0-based) of the pixel.',
+
required=False, dataType='float')
+
.param('units', 'Units used for left and top. base_pixels are pixels '
+
'at the maximum resolution, pixels and mm are at the specified '
+
'magnfication, fraction is a scale of [0-1].', required=False,
+
enum=sorted(set(TileInputUnits.values())),
+
default='base_pixels')
+
.param('frame', 'For multiframe images, the 0-based frame number. '
+
'This is ignored on non-multiframe images.', required=False,
+
dataType='int')
+
.errorResponse('ID was invalid.')
+
.errorResponse('Read access was denied for the item.', 403),
+
)
+
@access.public(cookie=True, scope=TokenScope.DATA_READ)
+
@loadmodel(model='item', map={'itemId': 'item'}, level=AccessType.READ)
+
def getTilesPixel(self, item, params):
+
params = self._parseParams(params, True, [
+
('left', float, 'region', 'left'),
+
('top', float, 'region', 'top'),
+
('right', float, 'region', 'right'),
+
('bottom', float, 'region', 'bottom'),
+
('units', str, 'region', 'units'),
+
('frame', int),
+
])
+
try:
+
pixel = self.imageItemModel.getPixel(item, **params)
+
except TileGeneralError as e:
+
raise RestException(e.args[0])
+
except ValueError as e:
+
raise RestException('Value Error: %s' % e.args[0])
+
return pixel
+
+
+
def _cacheHistograms(self, item, histRange, cache, params):
+
needed = []
+
result = {'cached': []}
+
tilesource = self.imageItemModel._loadTileSource(item, **params)
+
for frame in range(tilesource.frames):
+
if histRange is not None and histRange != 'round':
+
continue
+
checkParams = params.copy()
+
checkParams['range'] = histRange
+
if tilesource.frames > 1:
+
checkParams['frame'] = frame
+
else:
+
checkParams.pop('frame', None)
+
result['cached'].append(self.imageItemModel.histogram(
+
item, checkAndCreate='check', **checkParams))
+
if not result['cached'][-1]:
+
needed.append(checkParams)
+
if cache == 'schedule' and not all(result['cached']):
+
result['scheduledJob'] = str(self.imageItemModel._scheduleHistograms(
+
item, needed, self.getCurrentUser())['_id'])
+
return result
+
+
+
[docs]
+
@describeRoute(
+
Description('Get a histogram for any region of a large image item.')
+
.notes('This can take all of the parameters as the region endpoint, '
+
'plus some histogram-specific parameters. Only typically used '
+
'parameters are listed. The returned result is a list with '
+
'one entry per channel (always one of L, LA, RGB, or RGBA '
+
'colorspace). Each entry has the histogram values, bin edges, '
+
'minimum and maximum values for the channel, and number of '
+
'samples (pixels) used in the computation.')
+
.param('itemId', 'The ID of the item.', paramType='path')
+
.param('width', 'The maximum width of the analyzed region in pixels.',
+
default=2048, required=False, dataType='int')
+
.param('height', 'The maximum height of the analyzed region in pixels.',
+
default=2048, required=False, dataType='int')
+
.param('resample', 'If false, an existing level of the image is used '
+
'for the histogram. If true, the internal values are '
+
'interpolated to match the specified size as needed. 0-3 for '
+
'a specific interpolation method (0-nearest, 1-lanczos, '
+
'2-bilinear, 3-bicubic)', required=False,
+
enum=['false', 'true', '0', '1', '2', '3'], default='false')
+
.param('frame', 'For multiframe images, the 0-based frame number. '
+
'This is ignored on non-multiframe images.', required=False,
+
dataType='int')
+
.param('bins', 'The number of bins in the histogram.',
+
default=256, required=False, dataType='int')
+
.param('rangeMin', 'The minimum value in the histogram. Defaults to '
+
'the minimum value in the image.',
+
required=False, dataType='float')
+
.param('rangeMax', 'The maximum value in the histogram. Defaults to '
+
'the maximum value in the image.',
+
required=False, dataType='float')
+
.param('roundRange', 'If true and neither a minimum or maximum is '
+
'specified for the range, round the bin edges and adjust the '
+
'number of bins for integer data with smaller ranges.',
+
required=False, dataType='boolean', default=False)
+
.param('density', 'If true, scale the results by the number of '
+
'samples.', required=False, dataType='boolean', default=False)
+
.param('cache', 'Report on or request caching the specified histogram '
+
'for all frames. Scheduling creates a local job.',
+
required=False,
+
enum=['none', 'report', 'schedule'])
+
.errorResponse('ID was invalid.')
+
.errorResponse('Read access was denied for the item.', 403),
+
)
+
@access.public(scope=TokenScope.DATA_READ)
+
@loadmodel(model='item', map={'itemId': 'item'}, level=AccessType.READ)
+
def getHistogram(self, item, params):
+
_adjustParams(params)
+
params = self._parseParams(params, True, [
+
('left', float, 'region', 'left'),
+
('top', float, 'region', 'top'),
+
('right', float, 'region', 'right'),
+
('bottom', float, 'region', 'bottom'),
+
('regionWidth', float, 'region', 'width'),
+
('regionHeight', float, 'region', 'height'),
+
('units', str, 'region', 'units'),
+
('unitsWH', str, 'region', 'unitsWH'),
+
('width', int, 'output', 'maxWidth'),
+
('height', int, 'output', 'maxHeight'),
+
('fill', str),
+
('magnification', float, 'scale', 'magnification'),
+
('mm_x', float, 'scale', 'mm_x'),
+
('mm_y', float, 'scale', 'mm_y'),
+
('exact', bool, 'scale', 'exact'),
+
('frame', int),
+
('encoding', str),
+
('jpegQuality', int),
+
('jpegSubsampling', int),
+
('tiffCompression', str),
+
('style', str),
+
('resample', 'boolOrInt'),
+
('bins', int),
+
('rangeMin', int),
+
('rangeMax', int),
+
('roundRange', bool),
+
('density', bool),
+
])
+
_handleETag('getHistogram', item, params)
+
histRange = None
+
if 'rangeMin' in params or 'rangeMax' in params:
+
histRange = [params.pop('rangeMin', 0), params.pop('rangeMax', 256)]
+
if params.get('roundRange'):
+
if params.pop('roundRange', False) and histRange is None:
+
histRange = 'round'
+
+
cache = params.pop('cache', None)
+
if cache in {'report', 'schedule'}:
+
return self._cacheHistograms(item, histRange, cache, params)
+
result = self.imageItemModel.histogram(item, range=histRange, **params)
+
result = result['histogram']
+
# Cast everything to lists and floats so json will encode properly
+
for entry in result:
+
for key in {'bin_edges', 'hist', 'range'}:
+
if key in entry:
+
entry[key] = [float(val) for val in list(entry[key])]
+
for key in {'min', 'max', 'samples'}:
+
if key in entry:
+
entry[key] = float(entry[key])
+
return result
+
+
+
+
+
+
+
[docs]
+
@describeRoute(
+
Description('Get a list of additional images associated with a large image.')
+
.param('itemId', 'The ID of the item.', paramType='path')
+
.errorResponse('ID was invalid.')
+
.errorResponse('Read access was denied for the item.', 403),
+
)
+
@access.public(scope=TokenScope.DATA_READ)
+
@loadmodel(model='item', map={'itemId': 'item'}, level=AccessType.READ)
+
def getAssociatedImagesList(self, item, params):
+
try:
+
return self.imageItemModel.getAssociatedImagesList(item)
+
except TileGeneralError as e:
+
raise RestException(e.args[0], code=400)
+
+
+
+
[docs]
+
@describeRoute(
+
Description('Get an image associated with a large image.')
+
.notes('Because associated images may contain PHI, admin access to '
+
'the item is required.')
+
.param('itemId', 'The ID of the item.', paramType='path')
+
.param('image', 'The key of the associated image.', paramType='path')
+
.param('width', 'The maximum width of the image in pixels.',
+
required=False, dataType='int')
+
.param('height', 'The maximum height of the image in pixels.',
+
required=False, dataType='int')
+
.param('encoding', 'Image output encoding', required=False,
+
enum=['JPEG', 'PNG', 'TIFF'], default='JPEG')
+
.param('contentDisposition', 'Specify the Content-Disposition response '
+
'header disposition-type value.', required=False,
+
enum=['inline', 'attachment'])
+
.param('contentDispositionFilename', 'Specify the filename used in '
+
'the Content-Disposition response header.', required=False)
+
.produces(ImageMimeTypes)
+
.errorResponse('ID was invalid.')
+
.errorResponse('Read access was denied for the item.', 403),
+
)
+
@access.public(cookie=True, scope=TokenScope.DATA_READ)
+
def getAssociatedImage(self, itemId, image, params):
+
_adjustParams(params)
+
# We can't use the loadmodel decorator, as we want to allow cookies
+
item = loadmodelcache.loadModel(
+
self, 'item', id=itemId, allowCookie=True, level=AccessType.READ)
+
params = self._parseParams(params, True, [
+
('width', int),
+
('height', int),
+
('jpegQuality', int),
+
('jpegSubsampling', int),
+
('tiffCompression', str),
+
('encoding', str),
+
('style', str),
+
('contentDisposition', str),
+
('contentDispositionFileName', str),
+
])
+
_handleETag('getAssociatedImage', item, image, params)
+
try:
+
result = self.imageItemModel.getAssociatedImage(item, image, **params)
+
except TileGeneralError as e:
+
raise RestException(e.args[0], code=400)
+
if not isinstance(result, tuple):
+
return result
+
imageData, imageMime = result
+
self._setContentDisposition(
+
item, params.get('contentDisposition'), imageMime, image,
+
params.get('contentDispositionFilename'))
+
setResponseHeader('Content-Type', imageMime)
+
setRawResponse()
+
return imageData
+
+
+
+
+
+
_tileFramesParams = [
+
('framesAcross', int),
+
('frameList', str),
+
('left', float, 'region', 'left'),
+
('top', float, 'region', 'top'),
+
('right', float, 'region', 'right'),
+
('bottom', float, 'region', 'bottom'),
+
('regionWidth', float, 'region', 'width'),
+
('regionHeight', float, 'region', 'height'),
+
('units', str, 'region', 'units'),
+
('unitsWH', str, 'region', 'unitsWH'),
+
('width', int, 'output', 'maxWidth'),
+
('height', int, 'output', 'maxHeight'),
+
('fill', str),
+
('magnification', float, 'scale', 'magnification'),
+
('mm_x', float, 'scale', 'mm_x'),
+
('mm_y', float, 'scale', 'mm_y'),
+
('exact', bool, 'scale', 'exact'),
+
('frame', int),
+
('encoding', str),
+
('jpegQuality', int),
+
('jpegSubsampling', int),
+
('tiffCompression', str),
+
('style', str),
+
('resample', 'boolOrInt'),
+
('contentDisposition', str),
+
('contentDispositionFileName', str),
+
]
+
+
+
[docs]
+
@describeRoute(
+
Description('Composite thumbnails of multiple frames into a single image.')
+
.param('itemId', 'The ID of the item.', paramType='path')
+
.param('framesAcross', 'How many frames across', required=False, dataType='int')
+
.param('frameList', 'Comma-separated list of frames', required=False)
+
.param('cache', 'Cache the results for future use', required=False,
+
dataType='boolean', default=False)
+
.param('left', 'The left column (0-based) of the region to process. '
+
'Negative values are offsets from the right edge.',
+
required=False, dataType='float')
+
.param('top', 'The top row (0-based) of the region to process. '
+
'Negative values are offsets from the bottom edge.',
+
required=False, dataType='float')
+
.param('right', 'The right column (0-based from the left) of the '
+
'region to process. The region will not include this column. '
+
'Negative values are offsets from the right edge.',
+
required=False, dataType='float')
+
.param('bottom', 'The bottom row (0-based from the top) of the region '
+
'to process. The region will not include this row. Negative '
+
'values are offsets from the bottom edge.',
+
required=False, dataType='float')
+
.param('regionWidth', 'The width of the region to process.',
+
required=False, dataType='float')
+
.param('regionHeight', 'The height of the region to process.',
+
required=False, dataType='float')
+
.param('units', 'Units used for left, top, right, bottom, '
+
'regionWidth, and regionHeight. base_pixels are pixels at the '
+
'maximum resolution, pixels and mm are at the specified '
+
'magnfication, fraction is a scale of [0-1].', required=False,
+
enum=sorted(set(TileInputUnits.values())),
+
default='base_pixels')
+
+
.param('width', 'The maximum width of the output image in pixels.',
+
required=False, dataType='int')
+
.param('height', 'The maximum height of the output image in pixels.',
+
required=False, dataType='int')
+
.param('fill', 'A fill color. If output dimensions are specified and '
+
'fill is specified and not "none", the output image is padded '
+
'on either the sides or the top and bottom to the requested '
+
'output size. Most css colors are accepted.', required=False)
+
.param('magnification', 'Magnification of the output image. If '
+
'neither width for height is specified, the magnification, '
+
'mm_x, and mm_y parameters are used to select the output size.',
+
required=False, dataType='float')
+
.param('mm_x', 'The size of the output pixels in millimeters',
+
required=False, dataType='float')
+
.param('mm_y', 'The size of the output pixels in millimeters',
+
required=False, dataType='float')
+
.param('exact', 'If magnification, mm_x, or mm_y are specified, they '
+
'must match an existing level of the image exactly.',
+
required=False, dataType='boolean', default=False)
+
.param('frame', 'For multiframe images, the 0-based frame number. '
+
'This is ignored on non-multiframe images.', required=False,
+
dataType='int')
+
.param('encoding', 'Output image encoding. TILED generates a tiled '
+
'tiff without the upper limit on image size the other options '
+
'have. For geospatial sources, TILED will also have '
+
'appropriate tagging. Pickle emits python pickle data with an '
+
'optional specific protocol', required=False,
+
enum=EncodingTypes, default='JPEG')
+
.param('jpegQuality', 'Quality used for generating JPEG images',
+
required=False, dataType='int', default=95)
+
.param('jpegSubsampling', 'Chroma subsampling used for generating '
+
'JPEG images. 0, 1, and 2 are full, half, and quarter '
+
'resolution chroma respectively.', required=False,
+
enum=['0', '1', '2'], dataType='int', default='0')
+
.param('tiffCompression', 'Compression method when storing a TIFF '
+
'image', required=False,
+
enum=['none', 'raw', 'lzw', 'tiff_lzw', 'jpeg', 'deflate',
+
'tiff_adobe_deflate'])
+
.param('style', 'JSON-encoded style string', required=False)
+
.param('resample', 'If false, an existing level of the image is used '
+
'for the region. If true, the internal values are '
+
'interpolated to match the specified size as needed. 0-3 for '
+
'a specific interpolation method (0-nearest, 1-lanczos, '
+
'2-bilinear, 3-bicubic)', required=False,
+
enum=['false', 'true', '0', '1', '2', '3'])
+
.param('contentDisposition', 'Specify the Content-Disposition response '
+
'header disposition-type value.', required=False,
+
enum=['inline', 'attachment'])
+
.param('contentDispositionFilename', 'Specify the filename used in '
+
'the Content-Disposition response header.', required=False)
+
.produces(ImageMimeTypes)
+
.errorResponse('ID was invalid.')
+
.errorResponse('Read access was denied for the item.', 403)
+
.errorResponse('Insufficient memory.'),
+
)
+
@access.public(cookie=True, scope=TokenScope.DATA_READ)
+
@loadmodel(model='item', map={'itemId': 'item'}, level=AccessType.READ)
+
def tileFrames(self, item, params):
+
cache = params.pop('cache', False)
+
checkAndCreate = False if cache else 'nosave'
+
_adjustParams(params)
+
+
params = self._parseParams(params, True, self._tileFramesParams)
+
_handleETag('tileFrames', item, params)
+
pickle = _pickleParams(params)
+
if 'frameList' in params:
+
params['frameList'] = [
+
int(f.strip()) for f in str(params['frameList']).lstrip(
+
'[').rstrip(']').split(',')]
+
setResponseTimeLimit(86400)
+
try:
+
result = self.imageItemModel.tileFrames(
+
item, checkAndCreate=checkAndCreate, **params)
+
except TileGeneralError as e:
+
raise RestException(e.args[0])
+
except ValueError as e:
+
raise RestException('Value Error: %s' % e.args[0])
+
if not isinstance(result, tuple):
+
return result
+
regionData, regionMime = result
+
if pickle:
+
regionData, regionMime = _pickleOutput(regionData, pickle)
+
self._setContentDisposition(
+
item, params.get('contentDisposition'), regionMime, 'tileframes',
+
params.get('contentDispositionFilename'))
+
setResponseHeader('Content-Type', regionMime)
+
if isinstance(regionData, pathlib.Path):
+
BUF_SIZE = 65536
+
+
def stream():
+
try:
+
with regionData.open('rb') as f:
+
while True:
+
data = f.read(BUF_SIZE)
+
if not data:
+
break
+
yield data
+
finally:
+
regionData.unlink()
+
return stream
+
setRawResponse()
+
return regionData
+
+
+
+
[docs]
+
@describeRoute(
+
Description('Get parameters for using tile_frames as background sprite images.')
+
.param('itemId', 'The ID of the item.', paramType='path')
+
.param('format', 'Optional format parameters, such as "encoding=JPEG&'
+
'jpegQuality=85&jpegSubsampling=1". If specified, these '
+
'replace the defaults.', required=False)
+
.param('query', 'Addition query parameters that would be passed to '
+
'tile endpoints, such as style.', required=False)
+
.param('frameBase', 'Starting frame number (default 0). If c/z/t/xy '
+
'then step through values from 0 to number of that axis - 1. '
+
'The axis specification in only useful for cache reporting or '
+
'scheduling',
+
required=False, dataType='int')
+
.param('frameStride', 'Only use every frameStride frame of the image '
+
'(default 1). c/z/t/xy to use the length of that axis',
+
required=False, dataType='int')
+
.param('frameGroup', 'Group frames when using multiple textures to '
+
'keep boundaries at a multiple of the group size number. '
+
'c/z/t/xy to use the length of that axis.',
+
required=False, dataType='int')
+
.param('frameGroupFactor', 'Ignore grouping if the resultant images '
+
'would be more than this factor smaller than without grouping '
+
'(default 4)', required=False, dataType='int')
+
.param('frameGroupStride', 'Reorder frames based on the to stride '
+
'(default 1). "auto" to use frameGroup / frameStride if that '
+
'value is an integer.',
+
required=False, dataType='int')
+
.param('maxTextureSize', 'Maximum texture size in either dimension. '
+
'This should be the smaller of a desired value and of the '
+
'intended graphics environment texture buffer (default 16384).',
+
required=False, dataType='int')
+
.param('maxTextures', 'Maximum number of textures to use (default 1).',
+
required=False, dataType='int')
+
.param('maxTotalTexturePixels', 'Limit the total area of all combined '
+
'textures (default 2**30).',
+
required=False, dataType='int')
+
.param('alignment', 'Individual frame alignment within a texture. '
+
'Used to avoid jpeg artifacts from crossing frames (default '
+
'16).',
+
required=False, dataType='int')
+
.param('maxFrameSize', 'If specified, frames will never be larger '
+
'than this, even if the texture size allows it (default None).',
+
required=False, dataType='int')
+
.param('cache', 'Report on or request caching the resultant frames. '
+
'Scheduling creates a local job.',
+
required=False,
+
enum=['none', 'report', 'schedule'])
+
.errorResponse('ID was invalid.')
+
.errorResponse('Read access was denied for the item.', 403),
+
)
+
@access.public(cookie=True, scope=TokenScope.DATA_READ)
+
@loadmodel(model='item', map={'itemId': 'item'}, level=AccessType.READ)
+
def tileFramesQuadInfo(self, item, params):
+
metadata = self.imageItemModel.getMetadata(item)
+
options = self._parseParams(params, False, [
+
('format', str),
+
('query', str),
+
('frameBase', str),
+
('frameStride', str),
+
('frameGroup', str),
+
('frameGroupFactor', int),
+
('frameGroupStride', str),
+
('maxTextureSize', int),
+
('maxTextures', int),
+
('maxTotalTexturePixels', int),
+
('alignment', int),
+
('maxFrameSize', int),
+
])
+
for key in {'format', 'query'}:
+
if key in options:
+
options[key] = dict(urllib.parse.parse_qsl(options[key]))
+
result = large_image.tilesource.utilities.getTileFramesQuadInfo(metadata, options)
+
if params.get('cache') in {'report', 'schedule'}:
+
needed = []
+
result['cached'] = []
+
for src in result['src']:
+
tfParams = self._parseParams(src, False, self._tileFramesParams)
+
if 'frameList' in tfParams:
+
tfParams['frameList'] = [
+
int(f.strip()) for f in str(tfParams['frameList']).lstrip(
+
'[').rstrip(']').split(',')]
+
result['cached'].append(self.imageItemModel.tileFrames(
+
item, checkAndCreate='check', **tfParams))
+
if not result['cached'][-1]:
+
needed.append(tfParams)
+
if params.get('cache') == 'schedule' and not all(result['cached']):
+
result['scheduledJob'] = str(self.imageItemModel._scheduleTileFrames(
+
item, needed, self.getCurrentUser())['_id'])
+
return result
+
+
+
+
[docs]
+
@autoDescribeRoute(
+
Description('List all thumbnail and data files associated with a large_image item.')
+
.modelParam('itemId', model=Item, level=AccessType.READ)
+
.errorResponse('ID was invalid.')
+
.errorResponse('Read access was denied for the item.', 403),
+
)
+
@access.admin(scope=TokenScope.DATA_READ)
+
def listTilesThumbnails(self, item):
+
return self.imageItemModel.removeThumbnailFiles(item, onlyList=True)
+
+
+
+
[docs]
+
@autoDescribeRoute(
+
Description('Delete thumbnail and data files associated with a large_image item.')
+
.modelParam('itemId', model=Item, level=AccessType.READ)
+
.param('keep', 'Number of thumbnails to keep. Ignored if a key is '
+
'specified.', dataType='integer', required=False,
+
default=10000)
+
.param('key', 'A specific key to delete', required=False)
+
.param('thumbnail', 'If a key is specified, true if the key is a '
+
'thumbnail; false if the key is a data record',
+
dataType='boolean', required=False)
+
.errorResponse('ID was invalid.')
+
.errorResponse('Read access was denied for the item.', 403),
+
)
+
@access.admin(scope=TokenScope.DATA_WRITE)
+
def deleteTilesThumbnails(self, item, keep, key=None, thumbnail=True):
+
if not key:
+
return self.imageItemModel.removeThumbnailFiles(item, keep=keep or 0)
+
thumbnail = str(thumbnail).lower() != 'false'
+
query = {
+
'attachedToType': 'item',
+
'attachedToId': item['_id'],
+
'isLargeImageThumbnail' if thumbnail is not False else 'isLargeImageData': True,
+
'thumbnailKey': key,
+
}
+
file = File().findOne(query)
+
if file:
+
File().remove(file)
+
return [file]
+
+
+
+
[docs]
+
@autoDescribeRoute(
+
Description('Associate or replace a thumbnail or data file with a large_image items.')
+
.responseClass('File')
+
.modelParam('itemId', model=Item, level=AccessType.WRITE)
+
.param('key', 'A specific key to delete', required=True)
+
.param('thumbnail', 'If a key is specified, true if the key is a '
+
'thumbnail; false if the key is a data record',
+
dataType='boolean', required=False)
+
.param('mimeType', 'The MIME type of the file.', required=False)
+
.param('data', 'An image or data block to associated with the large_image item.',
+
paramType='body', dataType='binary')
+
.consumes('application/octet-stream')
+
.errorResponse('ID was invalid.')
+
.errorResponse('Read access was denied for the item.', 403),
+
)
+
@access.user(scope=TokenScope.DATA_WRITE)
+
def addTilesThumbnails(self, item, key, mimeType, thumbnail=False, data=None):
+
user = self.getCurrentUser()
+
thumbnail = str(thumbnail).lower() != 'false'
+
query = {
+
'attachedToType': 'item',
+
'attachedToId': item['_id'],
+
'isLargeImageThumbnail' if thumbnail is not False else 'isLargeImageData': True,
+
'thumbnailKey': key,
+
}
+
file = File().findOne(query)
+
if file:
+
File().remove(file)
+
data = cherrypy.request.body.read()
+
try:
+
import magic
+
mimeType = magic.from_buffer(data, mime=True) or mimeType
+
except Exception:
+
pass
+
mimeType = mimeType or 'application/octet-stream'
+
datafile = Upload().uploadFromFile(
+
io.BytesIO(data), size=len(data),
+
name='_largeImageThumbnail', parentType='item', parent=item,
+
user=user, mimeType=mimeType, attachParent=True)
+
datafile.update({
+
'isLargeImageThumbnail' if thumbnail is not False else 'isLargeImageData': True,
+
'thumbnailKey': key,
+
})
+
datafile = File().save(datafile)
+
return datafile
+
+
+
+
+