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@" />
CODE

returns:

<result 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

<operation opname="convert"
  infs="@INFS" in="@IN@" outfs="@OUTFS" in="@OUT@"
  [outres="@OUTRES@" outColor="@COLOR@" outDepth="@OUTDEPTH@" outStripped="@OUTSTRIPPED@"]
/>
CODE

returns:                      

<result 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" />

Tested formats:

  • 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@"/>
CODE

returns:

<result outfs = "String outfs" out = "String outRelURL" />

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@"/>
CODE


returns:

<result outfs = "String outfs" out = "String outRelURL" />

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:

<operation opname = "scale" width = "300" height = "200" x = "20" y = "30" />


This ends up as ImageMagick parameter "-crop 300x200+20+30". (It would extract the heart of the image only if it's size was 340x260)

Sometimes it may become difficult though 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:

<operation opname = "scale" width = "300" height = "200" x = "-1" y = "-1" />

(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@"/>
CODE

returns:

<result outfs = "String outfs" out = "String outRelURL" />

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@"/>
CODE

returns:

<result outfs = "String outfs" out = "String outRelURL" />

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@"/>
CODE

returns:

<result outfs = "String outfs" out = "String outRelURL" />

fliph

See flipv.

splitpdf

< operation opname = "splitpdf"
infs = "@INFS" in = "@IN@" outfs = "@OUTFS@" out = "@OUT@" />
CODE

returns:

<result outfs = "String outfs1" out = "String outRelURL1" />

<result outfs = "String outfs2" out = "String outRelURL2" />

...

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@"]/>
CODE


returns:

<result outfs = "String outfs" out = "String outRelURL" />

The overlay operation doesn't care about image sizes. It's the client's task to scale the overlay image accordingly.

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 much 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@"]
CODE

returns:

<result outfs = "String outfs" out = "String outRelURL" />

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 tool

  • default 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)

setOutputDepth

op.setOutputDepth(int outDepth)

Default output depth if not set by setOutputDepth() will be 8.

setOutputStripped

op.setOutputStripped(boolean outStripped)

Default is outStripped = true, which will remove all possibly included profiles:

  • ICC-Profiles

  • IPTC

  • EXIF (not for Helios ImageServer)

  • PATH

  • CLIP

setUpscale

op.setUpscale(boolean doUpscale)

If not explicitely called with op.setUpscale(true) ImageService will never upscale in any image transformation.

setRenderingIntent

op.setRenderingIntent(int renderingIntent)

Possible values for  renderingIntent:

  • 0 - perceptual

  • 1 - relative colorimetric

  • 2 - saturation

  • 3 - absolute colrimetric

  • 4 - perceptual with black point compensation

  • 5 - relative colorimetric with black point compensation

  • 6 - saturation with black point compensation

setLayoutOption

op.setLayerOption(String layoutOption)

If not set the layerOption defaults to "merge". This aggregates all channels of the input image.

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)

Choose values from "Gaussian"", "Impulse", "Laplacian", "Multiplicative", "Poisson", "Random", "Uniform".

The noise generators available in ImageMagick might be checked with convert -list noise.

The value is used directly as value for the "+noise" option to ImageMagick. There is
no effect when using JAI or Helios.

Operations

getInfo

HashMap <String,String> = op.getInfo()

Don't forget to use setInput().

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()

see  convert manager call  for supported formats

scale

void op.scale(int pxWidth, int pxHeight)

The resulting image will fit into a box of pxWidth x pxHeight. Upscaling will not be performed unless explicetely called for by setUpscale(true)

crop

void op.crop(int xOffset, int yOffset, int width, int height)

currently undefined results, if parameters lead to crop outside of input image

createOPI

void op.createOPI()

output format is derived from suffix of filename set by setOutput().

rotate

void op.rotate(int degree)

Backend Helios ImageServer only supports 0/90/180/270 degree rotation.

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)

see  overlay manager call  for a description of parameters
and constraints

Note: the overlay process will be delegated to ImageMagick no matter what backend is chosen.

setInput

void op.setInput(String inputFilesystem, String inputRelPathURL)

setOutput

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)

timecode  default value "0:0:0.000" interpreted as <hour>:<minute>:<second>.<framenumber>

Sample Scriptlet:

see "modules/image/sample-imageop.xml" and "modules/image/SampleImageOp.java"