API

General

Ichabod runs as a single-threaded process handling one request at a time. In order to support parallel processing, consider running multiple copies behind a proxy.

Command line options

The following command line options control various aspects of the rendering engine:

• --port

  The port to listen to for requests.

• --verbosity

  Debug output level. Specifying levels greater than zero will print out processing details to the console.

• --engine-verbosity

  Debug output level for rendering engine (qt webkit).

• --convert-verbosity

  Debug output level for image rasterization.

• --slow-response-ms

  Number of milliseconds before considering a response to be slow. This could happen for several reasons (e.g., waiting on an external asset request). Once a slow response is detected, debug output is turned all the way up to aid in debugging.

• --quantize

  Quantization method to use when downsampling images for animated gif output. By default, this is MEDIANCUT, which is a high quality method for reducing the number of colors in an image. Other options are:

  • THRESHOLD Fast and ugly color mapping
  • DIFFUSE Also fast, less ugly
  • ORDERED Very fast, very ugly
  • MEDIANCUT - Acceptable speed, high quality
  • MEDIANCUT_FLOYD - A modified version of MEDIANCUT using a different dithering algorithm.

• --version

  Output the version and quit.

• --statsd-host

  Optional statsd host.

• --statsd-port

  Optional statsd port.

• --statsd-ns

  Optional statsd namespace when sending activity.

JSON Request

Ichabod only accepts requests formatted as a JSON object. Here are the required and optional fields which are accepted:

• format Default is png. Also accepts gif.
• html HTML source code to render and rasterize. Also see url.
• url Optional. If no html is specified, the HTML from this URL will be used.
• js Javascript to execute after HTML is loaded and ready.
• rasterizer Optional. Name of the rendering object which can be controlled with javascript. Default is ichabod.
• output Path and filename to write the final image to. This must be accessible to the ichabod process.
• transparent Optional. Boolean value which can enable transparent background. Default is 1. Typically set to 0 for animated output.
• width Width of the virtual screen used to render the HTML.
• height Optional. Height of the virtual screen used to render the HTML. Default is -1, which will dynamically grow the height according to the HTML being rendered..
• crop_x Optional. X coordinate of final crop rectangle. Cropping takes place as the final step of rasterization.
• crop_y Optional. Y coordinate of final crop rectangle. Cropping takes place as the final step of rasterization.
• crop_w Optional. Width of final crop rectangle. Cropping takes place as the final step of rasterization.
• crop_h Optional. Height of final crop rectangle. Cropping takes place as the final step of rasterization.
• smart_width Optional. Dynamically grow the width according to HTML being rendered. Default is 1.
• css - Optional. Additional CSS to apply after the HTML is loaded.
• selector Optional. CSS selector to rasterize instead of the entire HTML body.
• load_timeout Optional. Maximum time allowed for a document to load before giving up. Typically used with url.
• enable_statsd Optional. Send activity to statsd.
• statsd_ns Optional. Namespace to use when communicating with statsd.

JSON Response

After processing a request, a response is returned to the client as a JSON string. The following fields are returned:

• conversion Boolean indicating whether a successful rasterization took place
• convert_elapsed Elapsed time for image rasterization
• errors List of human readable errors within ichabod and from the javascript console.
• path Output path of the rendered image. Will correspond to the request output field when successful.
• result Return value from the javascript. Can be null.
• run_elapsed Elapsed time for everything: handling the request, rendering the HTML and rastering the image.
• warnings List of human readable warnings, including javascript console output.

Runtime object

After ichabod loads the HTML (either specified directly in the request object, or loaded from a remote URL) then any javascript sent in the request is executed. In order to trigger rasterization, an internal javascript obejct (by default called ichabod) can be used. This object has several useful methods:

• setTransparent Takes a boolean argument indicating whether or not background transparency should be used when rendering.
• setQuality Set the quality of the render as an integer from 1 to 100. By default, this is 50 which is a good tradeoff between speed and quality.
• setScreen Set the dimensions of the virtual screen for rasterization. Specify x, y, width and height as integers.
• setFormat Set the format of the rasterization output. Use png or gif.
• setLooping Takes a boolean to enable or disable looping for animated output.
• snapshotPage Rasterizes the entire HTML into memory. This method can be called multiple times. When writing animated files, you can also specify a delay (in milliseconds). When writing animated output, all rasterized images are compiled into a gif. When writing a static image as output, only the last rasterized image is used.
• snapshotElements Rasterizes one or more CSS identifiers within the HTML. Otherwise, similar to snapshotPage.
• saveToOutput Saves the rasterized image(s) to disk. Once this method is called, no more rasterization can take place.
• setQuantizeMethod Changes the quanitization method for downsampling images when writing animated gifs.
• setSelector Sets the full CSS path to an element, which limits the rasterization to that area of the page.
• setCss Specifies additional CSS which is applied immediately to the page.
• setCropRect Specifies the absolute x, y, width and height of a cropping rectangle. This crop takes place as the last step of rasterization.
• setSmartWidth Takes a boolean argument to enable or disable using smart width calculation before rasterizing.