Editor API

Overview

Pixo allows you to manipulate the image and Pixo’s Plugin Settings from your application, thanks to the exec command.

The interface of exec is the following:

pixo_instance.exec('COMMAND', { param: 'value' })

where pixo_instance is a reference to an object instance of Pixo.Bridge:

const pixo_instance = new Pixo.Bridge({ option: 'value' })

Check the documentation for Pixo.Bridge constructor.

Because of its asynchronous nature, exec returns a Promise, which can be awaited, so your program knows when the operation is completed:

pixo_instance.exec('COMMAND')
    .then(state => console.log('COMMAND completed', { state }))

The promise is resolved with the updated state of Pixo Editor.

The cool part here is that instead of awaiting every single operation, you can chain a bunch of operations, and this will guarantee you that they will be executed in the same order they are invoked:

pixo_instance.exec('COMMAND1')
   .exec('COMMAND2')
   .exec('COMMANDN')

But even cooler is the fact that you don’t have to chain the commands, and they will still be executed in the right order, one after another:

pixo_instance.exec('COMMAND1');
pixo_instance.exec('COMMAND2');
pixo_instance.exec('COMMANDN');

State

The State object contains information about the current state of Pixo Editor: the currently active plugin, property values of every plugin, history, global settings, error state, etc. You can use the State object to update your external editing controls for Pixo Editor.

Subscribing to changes

You can get the new state by providing onStateChange callback to Pixo.Bridge constructor:

const pixo = new Pixo.Bridge({
    //... other options
    onStateChange: state => {
        //do something with the updated state
    },
});

The onStateChange callback will be executed every time the state changes, no matter if the change is triggered by the user within Pixo Editor or by the exec() method.

Receiving the new state

The exec() method will return a promise, which resolves when the command is executed, with the updated state:

pixo_instance.exec('ANY_COMMAND')
    .then(state => console.log('ANY_COMMAND completed', { state }))

There is also a GET_STATE command which returns current state.

Updating the state

Updating state happens through the SET_STATE command, which accept the new state as parameter. The new state is merged into the old/current state recursively, so this means that you may pass a partial state object:

const newstate = { active_plugin: 'draw' };
pixo_instance.exec('SET_STATE', { state: new_state });

Structure

The state is a JavaScript Object having the following structure:

  • active_plugin String one of the following: “adjustments”, “filters”, “draw”, “crop”, “stickers”, “text”, “transform”, “frame”, “blur”, “shape”
  • collapsed_panel Boolean whether the Property Panel is collapsed or not
  • plugins Object containing data for most of Pixo’s feature plugins; has the following structure:
    • background Object with the following structure:
      •  type String one of the following: “original”, “solidcolor”, “transparent”, “replacement”
      • bgcolor String CSS color for the “solidcolor” type
    • crop Object with the following structure:
      • orientation String one of the following: “portrait”, “landscape”
      • preset Number fixed crop ratio preset, e.g. 16 / 9, 4 / 3, etc.
      • ratio_locked Boolean
    • draw Object click to see structure
    • adjustments Object click to see structure
    • text Object click to see structure
    • filter String click to see possible values
    • frame Number selected frame index
    • shape String one of the following: “square”, “rectangle”, “circle”, “ellipse”, “roundsquare”, “roundrect”
  • history Object with the following structure:
    • length Number total history length
    • current Number current index in the history
  • error String error message (if there is an error, otherwise will be "")
  • track_history Boolean whether history is tracked or not

Command Index

Global operations

Getting & setting the State

pixo_instance.exec('GET_STATE')
    .then(state => { console.log('current state', state) });

When updating the state, the new state is merged into the old/current state recursively, so this means that you may pass a partial state object:

pixo_instance.exec('SET_STATE', { state: { active_plugin: 'draw' } });

More information about Pixo’s State.

Activate Plugin

pixo_instance.exec('ACTIVATE_PLUGIN', { plugin: 'filters' })

See list of available plugins.

Undo/Redo

pixo_instance.exec('UNDO')
pixo_instance.exec('REDO')

Enable/Disable history tracking

Pixo allows you to disable history (undo/redo) tracking, and enable it back at any time:

pixo_instance.exec('TRACK_HISTORY', { track_history: false })

Plugin operations

Select Filter

pixo_instance.exec('SELECT_FILTER', { name: 'Amarok' })

List of available filters:
  • None
  • Natural
  • Amarok
  • Klarendon
  • Larc
  • Mayfare
  • Autumn
  • Nightfall
  • Sepia
  • Grayscale
  • BlackWhite
  • Brownie
  • Vintage
  • Kodachrome
  • Technicolor
  • Polaroid
  • Reddish
  • Redify
  • Convolute-Sharpen
  • Convolute-ExtraSharp
  • Convolute-Light
  • Convolute-Dark
  • Convolute-Blur
  • Convolute-Emboss
  • Invert
  • Distressed

Insert Sticker

pixo_instance.exec('INSERT_STICKER', options)

Where options is an Object with the following shape:

  • src String The URL of the sticker image to be inserted
  • width Number (optional) The desired width of the sticker image. If the value is greater than 1 the width is set in pixels; otherwise it would be considered as a % of the edited image’s width, e.g. 0.65 = 65% of the edited image’s width. If not provided the natural width of the sticker image would be used unless larger than the edited image’s width.
  • height Number (optional) The desired height of the sticker image. If the value is greater than 1 the height is set in pixels; otherwise it would be considered as a % of the edited image’s height, e.g. 0.65 = 65% of the edited image’s height. If not provided the natural height of the sticker image would be used unless larger than the edited image’s height.
  • position (optional) String or Object with the following possible values:
    • "top"
    • "top-left"
    • "top-right"
    • "left"
    • "center"
    • "right"
    • "bottom"
    • "bottom-left"
    • "bottom-right"
    • Object with the following shape:
      • left Number The desired left boundary of the sticker image in pixels
      • top Number The desired top boundary of the sticker image in pixels
  • offset Object (optional) with the following shape:
    • x Number The desired horizontal offset in pixels (when larger than 1 ) or % of edited image’s width
    • y Number The desired vertical offset in pixels (when larger than 1 ) or % of edited image’s height

Example:

pixo_instance.exec('INSERT_STICKER', { src: 'https://pixoeditor.com/editor/shared/images/logo.png' })

Add Text

pixo_editor.exec('ADD_TEXT', options)

Where options is an Object with the following shape:

  • text String text message to insert
  • position (optional) String or Object with the following possible values:
    • "top"
    • "top-left"
    • "top-right"
    • "left"
    • "center"
    • "right"
    • "bottom"
    • "bottom-left"
    • "bottom-right"
    • Object with the following shape:
      • left Number The desired left boundary of the sticker image in pixels
      • top Number The desired top boundary of the sticker image in pixels
  • offset Object (optional) with the following shape:
    • x Number The desired horizontal offset in pixels (when larger than 1 ) or % of edited image’s width
    • y Number The desired vertical offset in pixels (when larger than 1 ) or % of edited image’s height
  • width Number (optional) The desired width of the text box. If the value is greater than 1 the width is set in pixels; otherwise it would be considered as a % of the edited image’s width, e.g. 0.65 = 65% of the edited image’s width. If not provided the width of the text box will be as big as the text inside.
  • height Number (optional) The desired height of the text box. If the value is greater than 1 the height is set in pixels; otherwise it would be considered as a % of the edited image’s height, e.g. 0.65 = 65% of the edited image’s height. If not provided the height of the text box will be as big as the text inside.
  • fontFamily String one of the following:
    • Arial
    • Verdana
    • Times New Roman
    • Georgia
    • Comic Sans MS
    • Pacifico
    • Roboto Condensed
    • Oswald
    • PT Sans
    • Open Sans Condensed
    • Ubuntu
    • PT Sans Narrow
    • Lobster
    • Yanone Kaffeesatz
    • Play
    • Amatic SC
    • Comfortaa
    • Poiret One
    • Russo One
    • Philosopher
    • Caveat
    • Jura
    • Marck Script
    • Bad Script
    • Montserrat Alternates
    • Neucha
    • Press Start 2P
    • Pattaya
  • fontSize Number from 10 to 100
  • lineHeight Number from -50 to 50
  • charSpacing Number
  • fontWeight String one of the following:
    • normal
    • bold
  • fontStyle String one of the following:
    • normal
    • italic
  • underline Boolean
  • linethrough Boolean
  • superscript Boolean
  • subscript Boolean
  • fill String any valid CSS color (incl. rgba)
  • textShadow Boolean
  • textShadowColor String any valid CSS color (incl. rgba)
  • textShadowOffsetX Number from -20 to 20
  • textShadowOffsetY Number from -20 to 20
  • textShadowBlur Number from 0 to 12
  • textStroke Boolean
  • strokeWidth Number  from 0 to 12
  • textBackground Boolean
  • textBackgroundColor String any valid CSS color (incl. rgba)
  • background Boolean
  • backgroundColor String any valid CSS color (incl. rgba)

Example:

pixo_editor.exec('ADD_TEXT', { text: 'Lorem Ipsum' })

Set Text Property

pixo_editor.exec('SET_TEXT_PROPERTY', { propname: 'fontFamily', value: 'Arial' })

Use this to change properties in the Text Property Panel.
List of available property names and their possible values:
  • fontFamily String one of the following:
    • Arial
    • Verdana
    • Times New Roman
    • Georgia
    • Comic Sans MS
    • Pacifico
    • Roboto Condensed
    • Oswald
    • PT Sans
    • Open Sans Condensed
    • Ubuntu
    • PT Sans Narrow
    • Lobster
    • Yanone Kaffeesatz
    • Play
    • Amatic SC
    • Comfortaa
    • Poiret One
    • Russo One
    • Philosopher
    • Caveat
    • Jura
    • Marck Script
    • Bad Script
    • Montserrat Alternates
    • Neucha
    • Press Start 2P
    • Pattaya
  • fontSize Number from 10 to 100
  • lineHeight Number from -50 to 50
  • charSpacing Number
  • fontWeight String one of the following:
    • normal
    • bold
  • fontStyle String one of the following:
    • normal
    • italic
  • underline Boolean
  • linethrough Boolean
  • superscript Boolean
  • subscript Boolean
  • textAlign String one of the following:
    • left
    • center
    • right
  • fill String any valid CSS color (incl. rgba)
  • textShadow Boolean
  • textShadowColor String any valid CSS color (incl. rgba)
  • textShadowOffsetX Number from -20 to 20
  • textShadowOffsetY Number from -20 to 20
  • textShadowBlur Number from 0 to 12
  • textStroke Boolean
  • strokeWidth Number  from 0 to 12
  • textBackground Boolean
  • textBackgroundColor String any valid CSS color (incl. rgba)
  • background Boolean
  • backgroundColor String any valid CSS color (incl. rgba)

Background

Replace existing background with solid color

pixo_instance.exec('SET_BACKGROUND_TYPE', { backgroundtype: 'solidcolor', bgcolor: 'red' })

Where “bgcolor” is a valid CSS color.

Remove background

pixo_instance.exec('SET_BACKGROUND_TYPE', { backgroundtype: 'transparent' })

Replace background

pixo_instance.exec('SET_BACKGROUND_TYPE', { backgroundtype: 'replacement', src: 'https://yourdomain.com/path/to/custom-background.jpg' })

Where “src” can be url or base64 image.

Restore original background

pixo_instance.exec('SET_BACKGROUND_TYPE', { backgroundtype: 'original' })

Select Frame

Pass the index of the frame to select:

pixo_instance.exec('SELECT_FRAME', { index: -1 })

-1 means no frame.

Select Shape

pixo_instance.exec('SELECT_SHAPE', { shape: 'circle' })

Available shapes:

  • rhombus
  • circle
  • ellipse
  • diamond
  • star
  • hexagon
  • octagon

Crop

To crop the image with specific crop aspect ratio:

pixo_instance.exec('CROP', { crop : { ratio: 16/9 } })

To crop the image with specific crop rectangle:

pixo_instance.exec('CROP', { crop : { left: 0, right: 0, width: 200, height: 200 } })

To set minimum and maximum crop rectangle dimensions:

pixo_instance.exec('SET_MIN_CROP_DIMENSIONS', { min_width: 150, min_height: 85 })
pixo_instance.exec('SET_MAX_CROP_DIMENSIONS', { max_width: 300, max_height: 169 })

To programatically toggle the aspect ratio lock:

pixo_instance.exec('TOGGLE_CROP_RATIO_LOCK')

Transform

To rotate the image:

pixo_instance.exec('TRANSFORM', { operation: 'rotate', direction: 'right' })

Possible directions: 'left' and 'right'.

To flip the image:

pixo_instance.exec('TRANSFORM', { operation: 'flip', direction: 'hor' })

Possible directions: 'hor' and 'ver'.

Color Adjustments

pixo_instance.exec('ADJUST', { propname: 'brightness', value: 0.05 })

List of property names and their value ranges:
  • brightness: -1 to 1
  • contrast: -1 to 1
  • hue-rotation: -2 to 2
  • saturation: -1 to 1
  • gamma-red: 0.01 to 2.2
  • gamma-green: 0.01 to 2.2
  • gamma-blue: 0.01 to 2.2
  • blur: 0 to 1
  • noise: 0 to 1000
  • pixelate: 2 to 20

Set Draw Property

pixo_instance.exec('SET_DRAWING_PROPERTY', { propname: 'linewidth', value: 20 })

List of property names and their values:
  • enabled Boolean
  • source String “brush” or “shape”
  • brushmode String one of the following:
    • Pencil
    • Circle
    • Spray
    • Blur
  • linewidth Number from 0 to 150
  • linecolor String any valid CSS color
  • shapecolor String any valid CSS color
  • shadowcolor String any valid CSS color
  • shadowwidth Number from 0 to 150
  • shadowoffset Number from 0 to 150
  • blur Number from 0 to 1

Insert Draw Shape

pixo_instance.exec('INSERT_DRAW_SHAPE', { value: 'rectangle' })

List with possible shapes to insert:

  • square
  • rectangle
  • circle
  • ellipse
  • roundsquare
  • roundrect