Table of Contents
The nuxeo-platform-imaging-tiling addon provides a service and adapters to generate picture tiles from a DocumentModel containing a picture or from a blob.
Tiling picture is usefull when you want to display in a web browser a very big image : accoring to the display settings and to the zoom level, the picture tiling service will generate you the needed picture tiles.
The Tiling Service addOn is composed of several layers :
REST API part
Provides a rest API to get the picture tiles from the server.
Depending of the URL, this API could be used to get the actual tiles (ie: picture), or to get information about the picture and the tile grid (XML or JSON).
Adapter part
An DocumentModelAdapter is provided to adapt the DocumentModel interface to an interface dedicated to picture tiling.
Default adapter simply extract the blob from the DocumentModel using either the default file schema, or using a provided xPath.
Other adapters can be provided to implement specific logic for source picture retrieveal (like multi-view-pictures) or even extract pre-computed tiles from the DB.
Tiling Service
This service is responsible for :
managing tiles cache
Because picture tiling can be long, this service maintains a FileSystem based cache of the input pictures, the generated tiles, and also some temporary resources used by the tiling process.
The service also manage a configurable garbage collector to clean up this cache.
manage PictureTilers
A PictureTiler is a Java Class that can extract a tile from a picture.
Current implementation provides ImageMagick based and Gimp based PictureTiler.
Default configuration requires ImageMagick :
because it is faster
because some treatments can not be done via gimp
because setup is easier
In order to define a tiling you will need to define 4 input parameters:
The input picture.
This input is represented by the ImageResource className in the API.
This ImageResource is usually provided via a DocumentModel adapter that will encapsulate the logic to find the input picture and will create a DocumentImageResource.
You may also directly create a BlobResource from a simple Blob.
The tiles width in pixel
The tiles height in pixel
The maximum number of tiles X/Y
This parameter represents the maximum number of tiles on the X or Y axis, that are needed to display the complete picture.
Basically it represent the grid size you will need to display the complete image using this tiling.
As you may have noticed the zoom factor is not an input parameter. In fact it is an output parameter : the service will compute the zoom factor that correspond to the tiling definition.
This choice may seem strange, but in most of the case, this is easier to use : you don't always know the size of the underlying image, but you know the space you have to display the tiled image (total width/height and number of tiles) and you know that you want to start with an image that is fully displayed.
Here is a quick explanation on how the tiling service work.
compute needed picture size.
From the tiling grid definition, the service will compute the needed input picture size.
find a scaled down picture if available
When the needed picture size is really smaller that the real input image, it may be interesting to generate a scalled down image.
This will slow down the process for the computation of the first tile, but will speed up the computation of all other tiles.
This is particularly true for format like JPEG that support to easily extract from them a smaller image.
This speed up the reading part (less bytes to read from DB/Hard Drive) and speed up the final scalling.
When scaling down the input picture is possible, the resulting image will be stored into the cache.
select the tiler
let the tiler do it's job
Depending on the tiler implementation, it may generate one tile at a tile (default for ImageMagick based tiler) or 9 tiles at a time (default for gimp tiler) or all tiles (possible for gimp tiler).
This behavior is transparent for the caller since, all generated tiles are cached.
ImageMagick 6.3.7 or later is needed : the Tiling Service uses the ImageMagick stream command that is not available in 6.2 (associated packages are libmagick and imagemagick).
Current implementation has only be tested under Linux.
If you want to use the Gimp tiler, you will need Gimp 2.x with python extensions.
Just drop the nuxeo-platform-imaging-tiling-XXX.jar in the nuxeo.ear/plugins/ directory and restart your server.
Configuration can be done using a extension point. Just create a file called pictures-tiles-config.xml in nuxeo.ear/config.
Use this extension point contrib to :
define the imagemagick command path (if default is not ok)
define the directory that will be used for cache
define the cachesize
define the GC parameters
NB : default config should be ok for any linux based system where imagemagick is setup via the package manager
Here is an example of a configuration file :
<?xml version="1.0"?>
<component name="my.projects.tiles.config">
<require>org.nuxeo.ecm.platform.pictures.tiles.default.config</require>
<extension target="org.nuxeo.ecm.platform.pictures.tiles.service.PictureTilingComponent"
point="environment">
<environment>
<parameters>
<!-- Gimp path variables -->
<parameter name="GimpExecutable">gimp</parameter>
<!-- ImageMagick path variables -->
<parameter name="IMConvert">convert</parameter>
<parameter name="IMIdentify">identify</parameter>
<parameter name="IMStream">stream</parameter>
<!-- global env variables -->
<parameter name="WorkingDirPath">/tmp/</parameter>
<!-- Max Disk cache usage in KB -->
<parameter name="MaxDiskSpaceUsageForCache">50000</parameter>
<!-- GC Interval in Minutes -->
<parameter name="GCInterval">10</parameter>
</parameters>
</environment>
</extension>
</component>
The tiling service can be very easily tested.
The Rest API for the tiling service use the felowing url pattern :
http://{server}/nuxeo/restAPI/getTiles/{repoId}/{docUUID}/{tWidth}/{tHeight}/{maxTiles}?format={format}&x={x}&y={y}
where
{server}
is the server DNS name of IP
{repoId}
is the id of the core repository that is used (use default if you don't know what it is).
{docUUI}
The uuid of the document that contains the image. If you use the default adapter, this document must use the fileschema and contain an image.
{tWidth}
the width in pixel of the tiles.
{tHeight}
the height in pixel of the tiles.
{maxTiles}
maximum number of tiles X/Y for the full image
{format}
the format of the tile information (JSON/XML)
this is used only if x and y are not supplied
{x}
x of the tile to be generated (starting from 0)
{y}
y of the tile to be generated (starting from 0)
Here are some examples :
http://server/nuxeo/restAPI/getTiles/default/950b0d27-2ca4-43e4-bb12-598ad6d64e86/200/150/2
Will send you the tiling information in XML for the picture contained in the doc 950b0d27-2ca4-43e4-bb12-598ad6d64e86 with a tile size of 200x150x2.
http://server/nuxeo/restAPI/getTiles/default/950b0d27-2ca4-43e4-bb12-598ad6d64e86/200/150/2?format=JSON
Will send you the tiling information in JSON for the picture contained in the doc 950b0d27-2ca4-43e4-bb12-598ad6d64e86 with a tile size of 200x150x2.
http://server/nuxeo/restAPI/getTiles/default/950b0d27-2ca4-43e4-bb12-598ad6d64e86/200/150/2?x=1&y=1
Will send you the tile (1,1) for the picture contained in the doc 950b0d27-2ca4-43e4-bb12-598ad6d64e86 with a tile size of 200x150x2.
The RestAPI provide a very basic test client. This test client was used during the development : this client is not pretty, not IE compliant, not dummy user proof.
You can access this test client via the rest API, just add the test=true to the URL.
http://server/nuxeo/restAPI/getTiles/default/950b0d27-2ca4-43e4-bb12-598ad6d64e86/200/150/2?test=true