Skip to main content

JSON Events Reference

This section describes the way to write commands (events) grouped to animation frames.

Basic JSON Structure​

  • Array of "frame" objects
  • Each frame contains an array of "events". Individual event types are described in the next section.
  • At the beginning of each frame
    • Input data are loaded
  • At the end of each frame
    • Simulation step is performed
    • Output data are saved 
{"frames":[
    {"events":[ // Frame #0
        {
            "event_type": "NEW_ARTWORK",
            // ...
        },
        {
            "event_type": // ...
        },
        // ...
    ]},
    {"events":[ // Frame #1
        {
            "event_type": // ...
        },
        // ...
    ]},
    {"events":[ // Frame #2
        // ...
    ]},
    // ...
]}

JSON Event Types​

Each animation frame consists of a list of events (commands). There are events in Rebelle for setting up the artwork, selecting brush presets, colors, moving stylus, etc.

NEW_ARTWORK​

Creates a new blank artwork with size width * height in units (by default pixels). Parameters other than width and height may be omitted.

Example:

{
    "event_type": "NEW_ARTWORK",
    "width": 640,
    "height": 480,
    "units": "px",  // default px, valid values: px, in, cm
    "dpi": 200,     // default 200
    "paper": {
        "preset": "Default/HM01 Handmade", // default Default/Aquarelle, may be absolute path
        "color": { "r": 128, "g": 255, "b": 128 }, // default 255,255,255
        "deckled_edges": false, // default true
        "paper_scale":  150 // default 100
    }
}

SET_PAPER​

Change paper or its params.

Example:

{
    "event_type": "SET_PAPER",
    "preset": "Default/HM01 Handmade", // default Default/Aquarelle, may be absolute path
    "color": { "r": 128, "g": 255, "b": 128 }, // default 255,255,255
    "deckled_edges": false, // default true
    "paper_scale":  150 // default 100
}

LOAD​

Loads the data from the provided path. Data and properties for event data are described in the Import/Export data section.

Example 1: (applies only to rgba-dry, rgba-wet)

{
    "event_type": "LOAD",
    "rgba_dry": {
        "filename": "tmp/some_image.exr",
        "blending": "NORMAL"
    }
}

Example 2: (applies only to bump-dry, bump-wet, water, wetness, velocity)

{
    "event_type": "LOAD",
    "water": {
        "filename": "tmp/water_data.exr",
        "function": "add",
        "multiplier": 1.2,
        "scaling": 2.3
    }
}

Example 3: (combined)

{
    "event_type": "LOAD",
    "rgba_dry": {
        "filename": "tmp/some_image.exr",
        "blending": "NORMAL"
    },
    "water": {
        "filename": "tmp/water_data.exr",
        "function": "add",
        "multiplier": 1.2,
        "scaling": 2.3,
        "wait_for_file_timeout_seconds": 10
    },
    "velocity": {
        "filename": "tmp/velocity_data.exr",
        "function": "average"
    }
}

"selection_mask" and "stencil_mask":​

  • Load a mask used for both painting and the simulation. If you need to use the mask only for painting, load it before the stroke, clear it before the simulation event or end of the frame, and then load it again before another stroke.
  • The mask should be in grayscale 8bit per channel png format. If another format is used, it will be internally converted to grayscale.
  • Type selection_mask is required, if clear layer behaviour is needed as in GUI application.
  • NOTE: At same time only one of selection_mask or stencil_mask should be used, othervise behaviour is undefined. (Technically, selection_mask is transferred to stencil_mask, so stencil_mask is overwriten then.)
{
    "event_type": "LOAD",
    "selection_mask": {
        "filename": "tmp/mask.png"
    }
}

SAVE​

Saves the data to the specified path. Data and properties for event data are described in the Import/Export data section.

Example:

{
    "event_type": "SAVE",
    "rgba_dry": {
        "filename": "tmp/rgba_dry_export.exr",
        "options": "tiled_mipmapped,colorconvert:sRGB:linear"
    },
    "velocity": {
        "filename": "tmp/velocity_export.exr",
        "options": "tiled_mipmapped"
    }
}

SET_BRUSH​

Sets tool and its various parameters. Parameters that are not specified in this event will keep their old values, however setting a new brush preset may change size, water, opacity and paint type as these may be stored in brush presets. Supported tools: OIL_AND_ACRYLIC, EXPRESS_OIL, WATERCOLOR, INK_PEN, PENCIL, PASTEL, MARKER, AIRBRUSH, BLEND, SMUDGE, CLONE, ERASER, WATER, DRY, BLOW.

Example:

{
    "event_type": "SET_BRUSH",
    "tool": "WATERCOLOR",
    "preset": "Default/Fan 1", // may be absolute path to preset too
    "size" : 20,
    "size_px" : 20, // use either size or size_px
    "water": 55,
    "opacity": 60,
    "pressure": 100,
    "dirty_brush": false,   // only works for OIL_AND_ACRYLIC, ignored for other tools
    "smudge_only_wet": false,// SMUDGE
    "keep_layer_wet": false,// available for tools with erase paint_type
    "keep_water": true,     // available for tools with erase paint_type
    "paint_type": "PAINT",  // BLEND|PAINT|PAINT_BLEND|PAINT_MIX|ERASE, not all tools support all paint types
    "only_water": true, // only paint water. Rgba and bump aren't painted. Only applicable to WATERCOLOR and INK_PEN tools. Usable for a "multilayer simulation".
    "glaze_mode": "TRANSPARENT",    // Watercolor tool supports TRANSPARENT, SEMI-OPAQUE and OPAQUE glazing modes, default value is TRANSPARENT, don’t set this parameter for other tools
    "color": { "r": 255, "g": 128, "b": 0 },

    // since Rebelle 5:
    "multi_color_brush": true,  // turns on multi colored brush feature, this allows multiple colors to be painted within single brush stroke, multiple colors and other parameters are set using "multi_color" object, see SET_BRUSH_COLOR event for further details
    "rotate_multi_color_brush": true,   // rotate multi color texture with brush rotation, also affects dirty brush effect
    "smudge": true, // override preset's smudge checkbox (in the Brush Creator). "preset" has to be set also.
    "spacing": 50, // override preset's spacing (in the Brush Creator). "preset" has to be set also.
    "opacity_multiplier": 2, // override preset's opacity multiplier (in the Brush Creator). "preset" has to be set also.
}

SET_ENGINE_PARAMS​

Sets various parameters found in the "Visual Settings" panel. All parameters are optional.

Example:

{
    "event_type": "SET_ENGINE_PARAMS",
    "absorbency": 5,        // range 0-10
    "re_wet": 5,            // range 0-10
    "texture_influence": 5, // range 0-10
    "edge_darkening": 5,    // range 0-10
    "create_drips": true,   // bool
    "drip_size": 5,         // range 1-10
    "drip_length": 5,       // range 1-10
    "impasto_depth": 5,     // range 0-10
    "gloss": 5,             // range 0-10
    "paper_texture": 5,     // range 0-10
    "paint_texture": 5,     // range 0-10
    "gran_enabled": true,   // bool       (since R5)
    "gran_strength": 5,     // range 0-10 (since R5)
    "gran_contrast": 5,     // range 0-10 (since R5)
    "gran_texture": 1,      // range 0-4  (since R5)
    "paused": true          // bool       (since R5), for pausing the simulation (diffusion)
}

POINTER_PRESS​

Performs pointer press, e.g. mouse click. By itself this event doesn’t cause anything to be drawn, only starts stroke drawing. Stroke consists of a pointer press, any number of pointer move events and a pointer release. POINTER_PRESS takes position and optional tablet data (pressure, pen tilt and pen rotation). It is recommended that all pointer events (press, move and release events) of a single stroke contain the same additional tablet data (for example all of them will have pressure and pen tilt specified), otherwise brush may behave erratically.

Example:

{
    "event_type": "POINTER_PRESS",
    "stroke_id": 25, // optional, id of the stroke useful when a stroke is split to multiple independent substrokes, this parameter ensures that all substrokes have the same "random start" parameters generated for the first stroke of this stroke_id and reused for all following strokes with the same stroke_id.
    "pos": {    // position in canvas coordinates, may be outside of the canvas
        "x": 400.0,
        "y": 0.0
    },
    "pen_tilt": {   // pen tilt in relation to drawing tablet’s x and y axis in degrees, optional
        "x": 60,
        "y": -45
    },
    "rotation": 45.0,   // pen rotation in degrees, optional
    "pressure": 0.6 // pen pressure, 0.0-1.0, optional
}

POINTER_MOVE​

Moves pointer to a new position, this causes segment from the previous position to be drawn with one move event delay (this extra move event influences trajectory). Takes the same parameters as POINTER_PRESS.

Brush color mixing internals​

The final color stored in the brush RGBA texture used for painting is:

C_final = (C_bottom * mix_ratio) + (C_dis * paint_ratio) + (C_prev * brush_ratio)

where:

  • C_bottom is the color under the brush
  • C_dis = (C_multicolor * dissipation) + (C_palette * (1 - dissipation)), where:
    • C_palette is the single palette color
    • C_multicolor is the color of the multicolor brush texture
  • C_prev is previous color from brush RGBA texture
  • mix_ratio, paint_ratio and brush_ratio are internally modified to sum up to 1, there is no parameter directly controlling brush_ratio
  • For PAINT paint type, mix_ratio = 0, paint_ratio = 1
  • For BLEND paint type, mix_ratio can be controlled, paint_ratio = 0
  • For PAINT_BLEND and PAINT_MIX, mix_ratio and paint_ratio can be set arbitrarily

Example:

{
    "event_type": "POINTER_MOVE",
    "pos": {    // position in canvas coordinates, may be outside of the canvas
        "x": 450.0,
        "y": 50.0
    },
    "pen_tilt": {   // pen tilt in relation to drawing tablet’s x and y axis in degrees, optional
        "x": 0,
        "y": 20
    },
    "rotation": 160.0, // pen rotation in degrees, optional
    "pressure": 0.8,   // pen pressure, 0.0-1.0, optional


    // since Rebelle 5:
    "dissipation": 0.5, // controls the ratio of multicolored (dirty) brush and the single palette color. Let's call the resulting color C_dis, 0.0-1.0, optional (0: single palette color only, 1: multicolor texture only)
    "paint_ratio": 1.0, // for PAINT_BLEND and PAINT_MIX paint types, controls the amount of new paint added (C_dis color from previous parameter), overrides paint curves from brush presets, 0.0-1.0, optional.
    "mix_ratio": 0.2    // for PAINT_MIX, PAINT_BLEND and BLEND paint types, controls the strength of mixing/blending, overrides mix/blend curves from brush presets, 0.0-1.0, optional
}

Related events: SET_BRUSH_COLOR

POINTER_RELEASE​

This event ends a stroke at the position specified in its parameters. If all pointer events in a stroke had the same exact position this event draws a single brush splat. Takes the same parameters as POINTER_PRESS.

Example:

{
    "event_type": "POINTER_RELEASE",
    "pos": {    // position in canvas coordinates, may be outside of the canvas
        "x": 300.0,
        "y": 300.0
    },
    "pen_tilt": {   // pen tilt in relation to drawing tablet’s x and y axis in degrees, optional
        "x": 50,
        "y": 50
    },
    "rotation": 50.0,   // pen rotation in degrees, optional
    "pressure": 0.0 // pen pressure, 0.0-1.0, optional
}

SET_CANVAS_TILT​

This event sets canvas tilt. Canvas tilt changes direction of fluid flow and can be freely changed at any moment even between simulation steps.

Example:

{
    "event_type": "SET_CANVAS_TILT",
    "tilt": {
        "x": 0.75,  // range -1 - 1, defines directional vector
        "y": 0.0
    },
    "enabled": 1    // optional, toggles canvas tilt on/off while preserving previous tilt value
}

FAST_DRY​

Performs fast dry operation, removes water but leaves the canvas wet. Takes no parameters.

Example:

{"event_type": "FAST_DRY"}

DRY​

Performs dry operation, removes water and leaves the canvas dry. Takes no parameters.

Example:

{"event_type": "DRY"}

WET_LAYER​

Performs wet the layer operation from panel layers. Takes no parameters.

Example:

{"event_type": "WET_LAYER"}

CLEAR_LAYER​

Performs the clean layer operation from panel layers. Implicitly, all data are cleared. Optional values are rgba_dry, rgba_wet, wetness, water, bump_dry, bump_wet, velocity, selection_mask, all boolean, default true. If some sublayers, like water or wetness need to be preserved, set them to false.

NOTE: If selection_mask is true (include implicit true), layer is cleared as by "Del" in GUI, and other options are ignored.

Example:

{
    "event_type": "CLEAR_LAYER",
    "wetness": false,
    "water": false,
    "selection_mask": false
}

SIMULATION​

At the end of each frame, a simulation step is implicitly performed. This event can be used to perform multiple simulation steps in a single frame.

Example: 1 simulation step is performed within a single frame:

{"events":[]}

Example: 5 simulation steps are performed within a single frame (4 explicit + 1 implicit):

{"events":[
    {
        "event_type": "SIMULATION",
        "repeats": 4
    }
]}

LOAD_MASK​

Unsupported since Rebelle v5, use LOAD with selection_mask or stencil_mask instead.

CLEAR_MASK​

Clear stencil or selection mask loaded with LOAD event, type selection_mask or stencil_mask. If both optional values are true, behaviour is undefined.

Example:

{
    "event_type": "CLEAR_MASK",
    "selection_mask": false // optional
    "stencil_mask": true // optional, default
}

SET_TOOL​

Switches to a new tool. Note that switching to a different tool does not carry over parameters set to the previously selected tool. Can be also set with SET_BRUSH. Not recommended to change during stroke painting.

Example:

{
    "event_type": "SET_TOOL",
    "tool": "WATERCOLOR"
}

SET_BRUSH_PRESET​

Sets a new brush preset to the currently selected tool, this may change other brush parameters. Can be also set with SET_BRUSH. Not recommended to change during stroke painting.

Example:

{
    "event_type": "SET_BRUSH_PRESET",
    "preset": "Default/Fan 1"       // may be absolute path
}

SET_BRUSH_PARAMS​

Sets brush parameters, these are: size, water, opacity and pressure. Can be also set with SET_BRUSH. Not recommended to change during stroke painting.

Example:

{
    "event_type": "SET_BRUSH_PARAMS",
    "size": 40,
    "size_px" : 20, // use either size or size_px
    "water": 50,
    "opacity": 80,
    "pressure": 100,
    "dirty_brush": true
}

SET_PAINT_TYPE​

Sets paint type to selected tool, different tools support different sets of paint types. Can be also set with SET_BRUSH. Not recommended to change during stroke painting.

ToolSupported Paint Types
OIL_AND_ACRYLIC, EXPRESS_OIL, WATERCOLOR, INK_PENBLEND, PAINT, PAINT_BLEND, PAINT_MIX, ERASE
PENCIL, PASTEL, MARKER, AIRBRUSHBLEND, PAINT, ERASE, PAINT_BLEND (since Rebelle 5)
BLEND, SMUDGE, CLONE, WATER, DRY, BLOW, ERASERno supported paint types

Example:

{
    "event_type": "SET_PAINT_TYPE",
    "paint_type": "PAINT_BLEND"
}

SET_GLAZE_MODE​

Sets glazing mode for the selected tool, should be only used for WATERCOLOR. Can be also set with SET_BRUSH. Not recommended to change during stroke painting.

Example:

{
"event_type": "set_glaze_mode",
"glaze_mode": "transparent",    // watercolor tool supports transparent, semi-opaque and opaque glazing modes, default value is transparent
}

SET_BRUSH_COLOR​

Sets color that is used for painting. Can be also set with SET_BRUSH. Not recommended to change during stroke painting (but may work for OIL_AND_ACRYLIC tool).

Also used to set parameters for multicolored brush. Multicolor brush texture is fully filled by color specified in color parameter, if this parameter is not present then this event adds a new color on top of previous texture colors. Note that using multicolored brush (and/or rotate_multi_color_brush brush parameter) changes behavior of "glazing" tools (all painting tools except OIL_AND_ACRYLIC), color blending and mixing works differently, closer to how OIL_AND_ACRYLIC tool works. (Implemented since Rebelle 5)

For more details about how the final brush color is computed, see the POINTER_MOVE event.

Example:

{
    "event_type": "SET_BRUSH_COLOR",
    "color": { "r": 255, "g": 0, "b": 0 },   // also fills multicolor texture

    // since Rebelle 5:
    "multicolor": {
        "seed": 1234,   // sets seed for randomly generated parameters, if not specified then new seed is generated using global random generator, this generator is only used if noise scale and offset aren’t set
        "threshold": 0.5,   // threshold used for noise, range 0-1
        "scale_with_brush": true, // if set noise scale and offset will scale with brush size, note that without setting multicolor parameters again after changing brush size the multicolor texture will not be recomputed
        "scale": { // sets noise scale, overridden by per color scale
            // either exact scale
            "x": 1.5,
            "y": 0.75,
            // or range for randomly generated scale
            "x_range": {"min": 0.5, "max": 1.0},    // 0 < min < max
            "y_range": {"min": 0.2, "max": 4.5}
        },
        "offset": { // sets noise offset, overridden by per color offset
            // either exact value
            "x": -320,
            "y": 14,
            // or range for randomly generated offset
            "x_range": {"min": -300, "max": 300},       // min < max
            "y_range": {"min": -0.5, "max": 0.5}
        },
        "multi_color_list": [
            // list containing colors to be applied to multicolor texture, each color can also have a scale, offset, threshold and "scale_with_brush" specified, overriding their respective parameters above
            {
                "color": { "r": 255, "g": 0, "b": 0 },
                "threshold": 0.1,
                "offset": {
                    "x": 10,
                    "y": 5
                },
                "scale": {
                    "x": 0.2,
                    "y": 0.2
                }
            },
            {
                "color": { "r": 0, "g": 255, "b": 0 },
                "scale": {
                    "x_range": {"min": 1.5, "max": 2.5},
                    "y_range": {"min": 1.0, "max": 5.0}
                }
            },
            {
                "color": { "r": 0, "g": 0, "b": 255 },
                "scale_with_brush": false,
                "threshold": 0.8,
                "offset": {
                    "x": -10,
                    "y": 320
                }
            },
            {
                "color": { "r": 255, "g": 0, "b": 255 }
            }
        ]
    }
}

SET_CLONE_PICK_POS​

Sets source position for clone tool, same as holding alt key and clicking on canvas with clone tool active. Needs to be set before the first stroke with the clone tool.

Example:

{
    "event_type": "SET_CLONE_PICK_POS",
    "pos": { 
        "x": 500,
        "y": 500
    }
}

SET_RANDOM_SEED​

Sets a seed for the random generator used in Rebelle. Needed when you need to render your JSON file multiple times and always get the same result. (Implemented since Rebelle 5)

Example:

{
    "event_type": "SET_RANDOM_SEED",
    "seed": 12345 // unsigned int
}

SET_PIGMENTS​

Enables or disables Pigments color mixing (Implemented since Rebelle 5)

Example:

{
    "event_type": "SET_PIGMENTS",
    "enabled": true // bool
}
Last updated on