getimage

The getimage command extracts image data from resources hosted on the Express Server.

Syntax

The getimage command may be invoked in several ways.

The following extracts an image from the specified item, corresponding to the specified region, and fitting within the specified dimensions:

getimage?cat=<catalog-name>&item=<item-id>&rgn=
<left,top,right,bottom>&wid=<pixels>&hei=<pixels>

The following extracts an image from the specified item, corresponding to the centerpoint and resolution level, and fitting the specified dimensions:

getimage?cat=<catalog-name>&item=<item-id>&cp=
<centerx,centery>&lev=<reslevel>&wid=<pixels>&hei=<pixels>

Parameters

The following parameters may be used with the getimage command:

cat

The catalog name.

item

The ID of the item to extract. The itemid is the folder path to the item plus the item name (or iserv-catalog-index, which specifies the spatial index).

bg

This specifies the background color to be used in the image. This is expressed as a hexadecimal sequence of 6 digits, in the order RRGGBB.

cp and lev

cp specifies the center point of the requested image extraction. This is specified in resolution independent coordinates, unless the parameter geo=true is also present, in which case it is expressed in geospatial coordinates. lev specifies the resolution level at which to extract. Note: Usage of the cp and lev parameters precludes usage of rgn. That is, use either rgn, or cp and lev.

geo

Optional. If geo is present and set to "true", then the coordinates expressed in rgn (or cp) are interpreted as geospatial coordinates. If not present or set to false, then the coordinates are interpreted as resolution independent.

hei

The target height (in pixels) of the extracted image.

method

Specifies how the extracted region is to be computed and processed in order to satisfy the request. The method parameter may have one of the values described below.

The default method is crop.

crop

The crop method returns an image that matches the requested region exactly and is scaled to the natural level closest in dimensions to the specified bounds. Unless the requested dimensions exactly match the natural levels of the source image, the returned image will either be larger or smaller than the requested dimensions.

The aspect ratio matches the source image exactly.

To guarantee that the returned image will fit inside of the requested dimensions, use the cropinside method.

For more information, see crop.

cropinside

This method is the same as crop except that cropinside guarantees that the entire requested region will fit inside the specified bounds without changing the bounds.

For more information, see cropinside.

fit

This method returns an image whose dimensions are exactly as specified in the request. The requested region is scaled to the closest natural level that will satisfy the dimensions, and may be expanded or clipped to fit the bounds. Since it scales the image to the closest natural level, the returned image may not contain the entire requested region.

The aspect ratio matches the source image exactly.

Use the fitinside method to guarantee the entire region fits within the specified dimensions.

For more information, see fit.

fitinside

This method is the same as fit except that fitinside guarantees that the entire requested region will fit inside of the specified bounds without clipping.

For more information, see fitinside.

scale

The width and height specify a bounding-box; the image is scaled to the maximum resolution that will fit within this box. The aspect ratio remains unchanged, and the width and height of the requested region are scaled equally until one of the requested dimensions is reached.

For more information, see scale.

fill

This is the same as scale, except that the image is stretched to fit both bounds exactly, adjusting the aspect ratio as required.

For more information, see fill.

oif

Specifies the output image format. Can be one of the following:

• jpg
• tif
• bmp
• png
• gif

rgn

The region of the source image to extract. This is specified in resolution independent coordinates, unless the parameter geo=true is also present, in which case it is expressed in geospatial coordinates. Note: Usage of the rgn parameter precludes usage of cp and lev. That is, use either rgn, or cp and lev.

transparent

Optional. If transparent is used and set to "true", Express Server returns an alpha band for image types that support alpha bands, such as PNG. A value of "false" ensures that no alpha band is returned.

txn

Performs an opaque query against the image.

wid

The target width (in pixels) of the extracted image.

Examples

The following examples are "live" in that they contain real URLs that will access an Express Server. Change the hostname to your host to see your own server's responses to these queries.

The following returns the entirety of the specified image, at a natural scale that will fit within 400x400 dimensions:

http://demo.lizardtech.com/lizardtech/iserv/getimage?cat=Geo&item=Seattle_toposkin_DEM.sid&wid=400&hei=400&oif=jpg&rgn=0,0,1,1

The following returns the upper left quarter of the specified image, at a natural scale that will fit within 400x400 dimensions:

http://demo.lizardtech.com/lizardtech/iserv/getimage?cat=Geo&item=Seattle_toposkin_DEM.sid&wid=400&hei=400&oif=jpg&rgn=0,0,.25,.25

The following returns the upper left quarter of the specified image, scaled so that either the width or height fit the specified dimensions exactly:

http://demo.lizardtech.com/lizardtech/iserv/getimage?cat=Geo&item=Seattle_toposkin_DEM.sid&wid=400&hei=400&oif=jpg&rgn=0,0,.25,.25&method=scale

The following returns the specified geospatial region:

http://demo.lizardtech.com/lizardtech/iserv/getimage?cat=Geo&item=Seattle_toposkin_DEM.sid&wid=400&hei=400&geo=true&rgn=600000.000000,5250000.000000,610000.000000,5240000.000000&method=fit

The following is the same query as the one above but expressed in the hierarchical query format:

http://demo.lizardtech.com/lizardtech/iserv/catalogs/Geo/Seattle_toposkin_DEM.sid/cmd/getimage/wid/400/hei/400/oif/jpg/rgn/0,0,.25,.25/method/scale