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"
| Name | Allowed values | Description |
|---|---|---|
file | required, no default | The source file data represented as FileBlob |
src_type | scr | zxp, required, no default | The source file type |
dest_type | png | gif | jpg, default=png | Output file format. Only 'gif' supports flashing. Other output file types will only render first flash frame which is selectable with flash_step |
zoom | 0..100, float, default=1 | Set this if you need to resize the source image. In case both width and height parameters are set, this parameter will be ignored |
width | 0 or more, int, default=0 | The width of the destination image. When this value is 0, the destination width will be calculated from height and zoom parameters |
height | 0 or more, int, default=0 | The height of the destination image. When this value is 0, the destination height will be calculated from width and zoom parameters |
crop | 0 | 1, default=0 | Whether 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_step | 0 | 1, default=0 | The 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_flash | 0 | 1 , defaul=0 | Disables flashing of a source image (only matters for gif output format) |
compression_level | 0-9, default=9 | No-loss compression level for png output. Higher is better, but slower |
quality | 0-1, default=0.8 | Quality level for jpg output. Higher is better, but makes larger files |
output | json | url | bin, default=json | Output 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. |
cutsrc | array, default=false | The 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 |
cutdest | array, default=false | The 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.
| Field | Description |
|---|---|
props | The 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. |
data | The 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 number | Description |
|---|---|
| bit 0 | Vertical direction: 0 = top-to-down, 1 = down-to-top |
| bit 1 | Horizontal direction: 0 = left-to-right, 1 = right-to-left |
| bit 2 | First direction: 0 = horizontal first, 1 = vertical first |
| bit 3 | Pass direction: 0 = one-way scan, 1 = ping-pong |
| bit 4 | Row height: 0 = row is one pixel height, 1 = row is "attribute" height |
| bit 5-6 | Where 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 |