ImageService API
Configure advanced image processing, for example in multi-pages files.
Introduction
scale, crop, etc. generally don't care if the input file has multiple pages. It's your responsibility to split input, typically with splitPDF.
Output format is deduced from suffix. Available suffixes depend on the configured backends. Helios ImageServer does not support PNG.
We don't have a facility to save different layers of images as storage items. Therefore several layers are always flattened on output.
The input color profile is either the embedded profile or the default profile
as configured in the ImageService setup. There is only a single profile per
colorspace.
Manager Interface
JPEG quality
<operation ... outJPEGQuality = "<NUMBER> " />
NUMBER := 0 .. 100
0 - worst quality
100 - best quality
default: from ImageService configuration, installation default = 80
info
<operation opname = "info" infs = "@INFS" in = "@IN@" />
convert
<operation opname="convert"
infs="@INFS" in="@IN@" outfs="@OUTFS" in="@OUT@"
[outres="@OUTRES@" outColor="@COLOR@" outDepth="@OUTDEPTH@" outStripped="@OUTSTRIPPED@"]
/>
returns:
- ImageMagick ok: JPEG, TIFF (only with LZW, Zip compression or uncompressed), PICT (with colour defects), PSD, PNG, GIF, EPS, PDF
- Helios ok: JPEG, TIFF, PNG, PSD, EPS, not implmented yet: PDF, GIF, PICT
- JAI' not implemented
scale
<operation opname="scale"
width="@WIDTH@" height="@HEIGHT@"
[outres="@OUTRES@" outColor="@COLOR@" outDepth="@OUTDEPTH@" outStripped="@OUTSTRIPPED@"]
[upscale="@UPSCALE@"]
[rendering-intent="@RENDERING-INTENT@"]
[layer-option="@LAYER-OPTION@"]
[add-noise="@ADD-NOISE@"]
infs="@INFS" in="@IN@" outfs="@OUTFS@" out="@OUT@"/>
returns:
If "outres" is not set physical dimensions (widthmm, heightmm) will be retained
by automatically calculating new resolution values.
layer-option defaults to "merge" which will aggregate all channels.
Set layer-option empty if you need to retain an alpha channel, which is
necessary for watermark images in the over
For overlay
operation
add-noise may contain one of these strings:
"Gaussian"
"Impulse"
"Laplacian"
"Multiplicative"
"Poisson"
"Random"
"Uniform"
Those noise generators should be available in every ImageMagick installation but to
be sure this can be checked with convert - list noise.
crop
<operation opname="crop"
width="@WIDTH@" height="@HEIGHT@" x="@X-OFFSET@" y="@Y-OFFSET@"
[outres="@OUTRES@" outColor="@COLOR@" outDepth="@OUTDEPTH@" outStripped="@OUTSTRIPPED@"]
infs="@INFS" in="@IN@" outfs="@OUTFS@" out="@OUT@"/>
returns:
Addition from 2014-03-11:
Up till now for cropping an image you have to specify width, height, x-offset and y-offset, e.g. by saying:
This ends up as ImageMagick parameter "-crop 300x200+20+30". (It would extract the heart of the image only if its size was 340x260)
Sometimes it may become difficult to calculate proper x/y offset values since the source image is first scaled.
For the the special case of cropping from the middle now there is some help available. You can just assign -1 to x or y:
(ImageMagick parameter "-crop 300x200+40+50" for source image size 380x300)
This saves you from evaluation proper x-offset and y-offset values. The feature will be available in 4.9.1 and 4.8.6.
opi
<operation opname="opi"
[outres="@OUTRES@" outColor="@COLOR@" outDepth="@OUTDEPTH@"]
infs="@INFS" in="@IN@" outfs="@OUTFS@" out="@OUT@"/>
returns:
If "outres" is not set 72dpi is assumed. Physical dimensions will be retained.
Setting "outStripped" will be accepted by ImageManager but not executed by the ImageService to avoid loss of information.
rotate
<operation opname="rotate"
degree="@DEGREE@"
[outres="@OUTRES@" outColor="@COLOR@" outDepth="@OUTDEPTH@" outStripped="@OUTSTRIPPED@"]
infs="@INFS" in="@IN@" outfs="@OUTFS@" out="@OUT@"/>
returns:
Backend Helios ImageServer only supports 0/90/180/270 degree rotation.
flipv
<operation opname="flipv"
[outres="@OUTRES@" outColor="@COLOR@" outDepth="@OUTDEPTH@" outStripped="@OUTSTRIPPED@"]
infs="@INFS" in="@IN@" outfs="@OUTFS@" out="@OUT@"/>
returns:
fliph
See flipv.
splitpdf
< operation opname = "splitpdf"
infs = "@INFS" in = "@IN@" outfs = "@OUTFS@" out = "@OUT@" />
returns:
overlay
overlay(String overlayFs, String overlayURLs, int opacity, String gravity, boolean tile, String extraOpts)
<operation opname="overlay"
infs="@INFS" in="@IN@" outfs="@OUTFS@" out="@OUT@"
overlay-fs="@OVERLAY-FS@" overlay="@OVERLAY@"
[outputColor="@COLOR@" outputStripped="@OUTPUT-STRIPPED@"]
[opacity="@OPACITY@" gravity="@GRAVITY@" tile="@TILE@" extra-opts="@EXTRA-OPTS@"]/>
returns:
Parameter description:
overlay-fs - filesystem of overlay image
overlay - relative path url to overlay image
opacity - defaults to 50, possible values 0 .. 100
gravity - defaults to "center", allowed values: northwest, north, northeast, west, center, east, southwest, south, southeast, center
tile - overrides any value in the gravity parameter, will overlay with as many tiles as possible
extra-opts - additional parameters to ImageMagick's composite command, not yet used
Adding noise to the watermark image must be done with the scale operation.
Note that "overlay" relies on ImageMagick's composite command. Even if Helios or JAI
is configured as backend ImageMagick will be used.
video-frame
Extract a single frame as image from a video.
<operation opname="video-frame"
timecode="@TIMECODE@
infs="@INFS" in="@IN@" outfs="@OUTFS@" out="@OUT@"/>
[outres="@OUTRES@" outColor="@COLOR@" outDepth="@OUTDEPTH@" outStripped="@OUTSTRIPPED@"]
returns:
Parameter description:
timecode - default value "0:0:0.000" interpreted as <hour>:<minute>:<second>.<framenumber>
Sample commands:
see "modules/image/sample-imageop-getinfo.xml" and "modules/image/SampleFillTemplate.java"
Java Interface
minimum service initialization:
ImageService service = ServiceLocator.getStaticService(ImageService.class);
ImageOp op = service.getImageOp();
op.setInput(fileSys, relPath);
customize service operations:
setJPEGQuality
op.setJPEGQuality(int quality)
quality = 1 = worst image quality, smallest filesize
quality = 100 = best image quality, largest filesize
since release 2018.3: quality ≤ 0 (zero or negative) = ignore configured quality and let the underlying tool use its default (for ImageMagick, the -quality option is omitted)
before 2018.3: zero or negative argument is passed to underlying tooldefault quality = 80
setOutputColor
op.setOutputColor(String color)
If setOutputColor() is not used the output image generally retains the color model of the input file.
"color" may be set to
"rgb"
"cmyk"
other colorspaces not tested
setOutputRes
op.setOutputRes(int resolution)
op.setOutputDepth(int outDepth)
Default output depth if not set by setOutputDepth() will be 8.
setOutputStripped
op.setOutputStripped(boolean outStripped)
ICC-Profiles
IPTC
EXIF (not for Helios ImageServer)
PATH
CLIP
setUpscale
op.setUpscale(boolean doUpscale)
setRenderingIntent
op.setRenderingIntent(int renderingIntent)
0 - perceptual
1 - relative colorimetric
2 - saturation
3 - absolute colorimetric
4 - perceptual with black point compensation
5 - relative colorimetric with black point compensation
6 - saturation with black point compensation
setLayoutOption
op.setLayerOption(String layoutOption)
To retain an alpha channel (e.g. TIFF image) use setLayoutOption(null).
The value is used directly as value for the "-layers" option to ImageMagick. There is
no effect when using JAI or Helios.
setAddNoise
op.setAddNoise(String noise)
The noise generators available in ImageMagick might be checked with convert-list noise.
The value is used directly as the value for the "+noise" option to ImageMagick. There is
no effect when using JAI or Helios.
Operations
getInfo
HashMap <String,String> = op.getInfo()
Returns HashMap with keys:
width=>"int pixelwidth"
height=>"int pixelheight"
x-res=>"int dpiX"
y-res=>"int dpiY"
widthmm=>"double widthmm"
heightmm=>"double heightmm"
col-space=>"String bw|gs|rgb|idx|cmyk|lab"
file-format=>"String suffix"
file-bytesize=>"long bytes"
convert
void op.convert()
scale
void op.scale(int pxWidth, int pxHeight)
crop
void op.crop(int xOffset, int yOffset, int width, int height)
createOPI
void op.createOPI()
rotate
void op.rotate(int degree)
flipV
void op.flipV()
flipH (see flipV)
splitPDF
ArrayList
<FileLocator>
op.splitPDF()
overlay
overlay(String overlayFs, String overlayURL, int opacity, String gravity, boolean tile, String extraOpts)
and constraints
setInput
void op.setInput(String inputFilesystem, String inputRelPathURL)
void op.setOutput(String outputFilesystem, String outputRelPathURL)
Output image format is derived from filename suffix. Currently tested are
.jpg
.tif
.pdf
videoFrame
Extract a single frame as image from a video.
void op.videoFrame(String timecode)
Sample Scriptlet:
see "modules/image/sample-imageop.xml" and "modules/image/SampleImageOp.java"