RejigHomeGet startedBrowse
Log in

Get started with Rejig

Rejig is a tool to create and process images programmatically. After describing the image you want, including its various layers, in a configuration file in YAML or JSON format, Rejig can process each of those layers and export the final image. These are called workflows; the configuration files are manifests.

This becomes especially useful as part of another application where you might want to process user-defined images in a consistent way without needing human intervention.

There are two ways of using Rejig:

  1. Install and use the Rejig CLI from your terminal
  2. Install the rejig-processing package in a Node.js project

Terminology

A quick overview of some concepts and what they mean:

ConceptMeaning
WorkflowDescribes the way an image is created, through combining various layers and effects.
ManifestA plain text file written in YAML or JSON that describes a workflow.
CLICommand Line Interface: a program that can be accessed through a terminal or command prompt.
YAMLA language used mainly for data. Very simple syntax and easy to read. Stored as a plain text file, e.g. example.yaml.
JSONA language used mainly for data. Similar to YAML but uses curly braces ({ and }). Stored as a plain text file, e.g. example.json.

Installing the Rejig CLI

In order to use the Rejig CLI, you will need to install it first.

  1. Ensure you have Node.js installed (v16 or higher)
    • On MacOS, you can install Homebrew, then run brew install nodejs
    • On Linux, you can use your package manager, e.g. sudo apt update && sudo apt install nodejs npm
  2. Install the Rejig CLI with npm install -g rejig-cli
  3. You can now run rejig help to see the available commands (most notably: rejig process <path-to-workflow-file>)

At any point in the future, you can update the CLI by running npm install -g rejig-cli again.

Creating your first workflow

Now that you have the Rejig CLI installed, you might wonder how you can create your first workflow. Hopefully you already have a code editor installed like Visual Studio Code, Notepad++, Sublime Text or any of the many other great options.

  1. Create a new YAML file (e.g. my-first-workflow.yaml) and open it in your preferred editor

  2. Add the following content:

    name: My first workflow

size:
  width: 512
  height: 512

layers:
  - content:
      type: solid
      color:
        r: 255
        g: 122
        b: 255
        a: 1
    opacity: 30
  - content:
      type: image
      location: https://placekitten.com/512/512?image=8

  3. Open your terminal or command prompt and navigate to the folder containing the YAML file (e.g. cd workflows)

  4. Run rejig process my-first-workflow.yaml

  5. Voilà! You should now have an image My first workflow.png in the same folder, containing a cute kitten photo 😸

Output image of a kitten with a purple overlay from above workflow (Attribution)

CLI commands & flags

The easiest way of finding out what the Rejig CLI can do is by running rejig help or rejig help <command>.

For example: rejig help process will show you how to use the process command. You'll see that it takes one argument, which is the path to a workflow or a folder.

By default, the output image will use the same file name as the workflow file (e.g. my-custom-workflow.yaml will output my-custom-workflow.png) unless the name property is present in the workflow file. In that case, it will use the name as the file name.

You might also have noticed that it takes two flags, which you can use like this: rejig process <path-to-workflow> --watch or rejig process <path-to-workflow> --out=some-folder-for-output.

Sharing workflows with push and pull

In order to make it easier to share workflows, Rejig allows you to push your workflows for others to pull. This also means you can pull existing workflows and use them.

When you have created a workflow you are happy with and you are ready to share it, you'll need to make sure you are logged in using the CLI, which you can do using rejig login.

Then you can push your workflow using the command rejig push <workflow-file> <name>. For example: rejig push my-custom-workflow.yaml kittens.

Workflows become available to others by referencing your username and the workflow name. For example, if your username is catlady and you created a workflow kittens, it will be available to others by the name catlady/kittens, by using the following command: rejig pull catlady/kittens or by using the workflow layer content type inside your workflow file.

You can also choose to push workflows with an optional tag. This is useful to provide different versions of a workflow as you make changes. When pushing or pulling you can specify a tag in this format: <username>/<workflow>:<tag>. Using the example above, you could push a workflow like this: rejig push my-custom-workflow.yaml kittens:v1.0.0 which would become available to others by referencing: catlady/kittens:v1.0.0. By default, if you don't specify a tag, it is set to latest.

You can see what workflows you have published using rejig list and inspect what tags are available for any workflow using rejig tags <username>/<workflow>.

Workflow schema

The full Workflow schema is available in the Rejig.Processing documentation.

To make it easier to edit JSON or YAML files in your code editor, you can add a reference to the Workflow schema by adding this to your workflow files:

YAML:

# yaml-language-server: $schema=https://raw.githubusercontent.com/Cryptacular/Rejig.Processing/master/json-schema/workflow.json

JSON:

{
  "$schema": "https://raw.githubusercontent.com/Cryptacular/Rejig.Processing/master/json-schema/workflow.json"
}

This should enable autocompletion and validation in your code editor (if supported) so you can see if the workflow you've created is valid.

Layer content types

For each layer you create, you can specify what type of content it contains (using the content property).

Content typeDescription
imageAdds an image from your local drive or a URL. Uses additional property location to specify where the image is located.
solidAdds a layer of a solid color. Uses additional property color with r, g,b and a values.
gradientAdds a linear gradient between two colors. Uses additional properties color and pos, each with from and to values.
workflowAdds a layer using the output of a workflow that's been published to Rejig, using the format <username>/<workflow> or <username>/<workflow>:<tag>.

Examples

Image

# Image
size:
  width: 256
  height: 256

layers:
  - content:
      type: image
      location: https://placekitten.com/256/256?image=7

A small square image of a kitten, generated from the above workflow (Attribution)

Solid

# Solid
size:
  width: 256
  height: 256

layers:
  - content:
      type: solid
      color:
        r: 255
        g: 0
        b: 122
        a: 1

An image of a pink square, generated from the above workflow

Gradient

# Gradient
size:
  width: 256
  height: 256

layers:
  - content:
      type: gradient
      color:
        from:
          r: 0
          g: 255
          b: 122
          a: 1
        to:
          r: 122
          g: 0
          b: 122
          a: 0.8
      pos:
        from:
          x: 256
          y: 0
        to:
          x: 0
          y: 256

An image with a gradient from dark purple in the bottom left corner to bright green in the top right corner

Workflow

# Workflow

size:
  width: 120
  height: 120

layers:
  - content:
      type: workflow
      workflow: cryptacular/something:1.0.4

An image with a gradient from yellow at the top to transparent at the bottom

Going beyond the basics

In the simple example above, we created a workflow with a single layer that referenced an image. By itself, that's not particularly useful. We can however do a few useful things with this image, such as scaling it up or down, moving it around, or placing it so it fits within the bounds of our image or making sure it covers the entire image.

Here is a list of properties we can add to any layer:

PropertyDescription
opacityThe opacity of the layer. 0 = transparent, 100 = fully visible.
positionWhere the layer is placed. Takes x and y values. Defaults to { x: 0, y: 0 }.
scaleScale the layer up and down in its x and y axes. Defaults to 1.
placementPlace the layer so it fits within the bounds of the image (fit), cover the whole image (cover), or stretch to fit (stretch). Defaults to custom.
originLets you specify where the origin of the layer content (e.g. image) is. The origin point is used as a reference point for positioning and scaling the layer content. Some examples: center center, top left, center right. Defaults to top left.
alignmentJust like origin except this controls where in the layer the content is placed (before position and scale are applied).
blendingModeThis changes how a layer affects the layers underneath it. By default this is set to normal which just draws the layer on top of the layers below. Blending modes like multiply and darken will make your image darker and ignores light values, whereas add and screen will make your image lighter and ignores dark values. Play around to see what works best.
maskThis is effectively a nested layer. However, instead of being drawn like a regular layer, it takes light and dark values of the mask and uses those to control the opacity of the layer this is used on. Black values will become transparent, whereas white values will remain visible.

An example of how you might use these properties:

size:
  width: 512
  height: 512

layers:
  - content:
      type: image
      location: https://placekitten.com/512/512?image=1
    mask:
      content:
        type: gradient
    blendingMode: overlay
  - content:
      type: image
      location: https://placekitten.com/512/512?image=1
    opacity: 100
    position:
      x: 0
      y: 0
    scale:
      x: 0.8
      y: 0.8
    placement: custom
    origin: center center
    alignment: center center

This results in the following image:

Output image from above workflow, with one kitten image overlaid onto another kitten image (Attribution)

Further topics coming soon