Skip to main content

convert

Converts graphics files and optionally cuts them into tiles

Access Point

POST https://api.zxlab.org/v1/convert

Parameters should be sent within POST packet having a mimetype "application/form-data"

NameAllowed valuesDescription
filerequired, no defaultThe source file data represented as FileBlob
src_typescr | zxp, required, no defaultThe source file type
dest_typepng | gif | jpg, default=pngOutput file format. Only 'gif' supports flashing. Other output file types will only render first flash frame which is selectable with flash_step
zoom0..100, float, default=1Set this if you need to resize the source image. In case both width and height parameters are set, this parameter will be ignored
width0 or more, int, default=0The width of the destination image. When this value is 0, the destination width will be calculated from height and zoom parameters
height0 or more, int, default=0The height of the destination image. When this value is 0, the destination height will be calculated from width and zoom parameters
crop0 | 1, default=0Whether crop is allowed or not. In case width and height parameters are both set, resulting image can be larger than given dimensions. In this case crop=1 will make the image cropped on the largest dimension. In case crop=0, whole image will be resized to be fit into the given dimensions completely
flash_step0 | 1, default=0The flash state which will be recognized as "first". For flash_step=0 normally INK and PAPER will be set. For flash_step=1 INK and PAPER will be exchanged
disable_flash0 | 1 , defaul=0Disables flashing of a source image (only matters for gif output format)
compression_level0-9, default=9No-loss compression level for png output. Higher is better, but slower
quality0-1, default=0.8Quality level for jpg output. Higher is better, but makes larger files
outputjson | url | bin, default=jsonOutput data format.
json will represent output image data as base64-encoded string inside the JSON object.
bin will output the binary image data with a correct mimetype header.
url will store the result image in the temporary storage on ZXLab cloud and the direct URL will be provided in the response JSON packet.
cutsrcarray, default=falseThe cutting job request for the source file. Setting this value to array will automatically set output property to json. For additional information read the Cutting Job description below
cutdestarray, default=falseThe cutting job request for the destination file. Setting this value to array will automatically set output property to json. For additional information read the Cutting Job description below

Cutting Job

The convert API method can cut both source or/and destination images to the specific blocks and output those blocks in the same response as an array of base64-encoded binary data.

In case cutsrc or cutdest is set, the cutting mode is automatically ON, however the output mode should be set to json, otherwise the error message will be returned.

Input Parameters

cutsrc and cutdest both have the same format, but cutsrc is applied to source image, while cutdest is applied to destination image. The value is stringified JSON object that has props and data properties.

FieldDescription
propsThe parameter list and order.

Default value is [["x", 0], ["y", 0], ["width", 8], ["height", 8], ["byteorder", 0x60]] that means by default first data value will be recognized as "x" coordinate or cutting rectangle, next as "y" and so on. In case some parameters are not set, the default values will be used. For example, you may not set width, height and byteorder for each block in case they are all the same.
dataThe array of parameters for each block. For example, if you need to cut two blocks from 50, 50 and from 30, 80 with 8x8 pixel size each and byteorder=0x60, you can set data as [[50, 50], [30, 80]]. Assume the second block is 16x24 pixels size, the data become [[50, 50], [30, 80, 16, 24]]. You can find more examples below.

Possible props keys are x, y, width, height and byteorder. First 4 are position and size of the block in pixels. The byteorder is a bitfield that describes the way how output data should be stored.

The byteorder bits are described below.

Bit numberDescription
bit 0Vertical direction: 0 = top-to-down, 1 = down-to-top
bit 1Horizontal direction: 0 = left-to-right, 1 = right-to-left
bit 2First direction: 0 = horizontal first, 1 = vertical first
bit 3Pass direction: 0 = one-way scan, 1 = ping-pong
bit 4Row height: 0 = row is one pixel height, 1 = row is "attribute" height
bit 5-6Where to add attributes? 0 = after the all pixel data, 1 = after the each row data, 2 = after the each "symbol", 3 = do not add attribute data

Cutting Response

Examples