How to use

How to use CamanJS

Which version do I use?

CamanJS is built into the dist folder, which is always kept up to date. In there, you will find four different files.

The files with 'full' in the URL include both the core library and all of the CamanJS plugins. The files without 'full' in the URL only include the core library, and plugins must be included separately if you wish to use them.

The 'min' files are the minified versions of each.

Basic Usage

Using CamanJS is simple. It goes something like this:

Caman('path/to/image.jpg', '#canvas-id', function () {
  this.brightness(10);
  this.contrast(-5);
  this.saturation(-50);
  // and so on...
  
  this.render();
});

You can also directly point to an image if you don't want to create a separate canvas element. In this case, the image element will be replaced with the canvas element, and the canvas will be drawn with the image content:

Caman("#image-id", function () {
  this.contrast(-5).render();
});

Resizing the Canvas

The canvas can be resized using the HTML5 data attributes data-camanwidth and/or data-camanheight, like this:

<img src="testimg.jpg" data-camanwidth="300" data-camanheight="150" />

Both the width and height are optional. If only one is given, the canvas will be resized proportionally.

JS Library Adapters

If you are already using a popular JS library on your site (such as jQuery, Mootools, ExtJS, etc), then there may be an adapter for CamanJS that integrates it with that library. Remember, CamanJS is fully standalone and isn't dependent on any library, but the option is there if you like a more tightly integrated environment.

All adapters are located in the adapters/ folder. Simply include them after you include CamanJS.

<script type="text/javascript" src="caman.full.min.js"></script>
<script type="text/javascript" src="adapters/jquery.js"></script>

<script type="text/javascript">
$("#caman-image").caman(function() {
  this.brightness(10).render();
});
</script>

Saving Images

You can also save images after they've been modified! With the current implementation, users will have to rename the file to something.(png|jpg) since they get redirected to the base64 encoding of the image and the browser doesn't know the file type. The save() function defaults to png, but you can override this and specify either png or jpg.

Caman('img/example.jpg', '#image-caman', function () {
  this.saturation(-20);
  this.brightness(10);
  
  this.render(function () {
    this.save('png'); // shows a download file prompt

    // or...
    this.toBase64(); //  base64 data URL representation of the image. useful if you want to upload the modified image.
  });
});

CamanJS Layering System

CamanJS now supports a powerful layering system, much like the one you would find in Photoshop or GIMP. Here's an example of how it works:

Caman('#test', function () {
  this.brightness(10);
  
  /*
   * Creates a new layer. Everything called inside the callback argument will be applied
   * to the new layer. Layers have some special layer-only functions such as setBlendingMode(),
   * opacity(), and copyParent(). In order to access the standard filters, you need to access them
   * through this.filter.
   */
  this.newLayer(function () {
    // There are many blending modes, more below.
    this.setBlendingMode('multiply');
    this.opacity(10);
    this.copyParent();
    
    this.filter.gamma(0.8);
    this.filter.contrast(50);
    
    /*
     * Yep, you can stack multiple layers! The further a layer is nested, the higher up on the layer
     * stack it will be.
     */
    this.newLayer(function () {
      this.setBlendingMode('softLight');
      this.opacity(10);
      this.fillColor('#f49600');
    });
    
    this.filter.exposure(10);
  });
  
  this.exposure(20);
  this.gamma(0.8);
  this.render();
});

Layer Blending Modes

These are all of the layer blending modes currently supported by CamanJS. You can also add new blending modes via plugins if you need some special functionality.

• normal
• multiply
• screen
• overlay
• difference
• addition
• exclusion
• softLight

Image Overlays

With the layering system, it's possible to load a new image into the layer canvas for some really great effects. The image can be either local or remote (if you have a local proxy setup).

Caman("#test", function () {
  this.contrast(5);

  this.newLayer(function () {
    this.setBlendingMode('softLight');
    this.opacity(20);

    this.overlayImage('images/overlay.jpg');
  });

  this.render();
});

Editing Remote Images

CamanJS can even edit images that are stored remotely. Since the browser enforces a same-origin policy for editing canvas data, we have to load the image data via a local proxy.

CamanJS comes with a PHP proxy (you're welcome to add a proxy in the language of your choice) that you can use in the proxies folder. Before you use CamanJS for editing, all you have to do to enable the proxy is:

// Will use the PHP proxy in the proxies folder.
Caman.remoteProxy = Caman.IO.useProxy('php');

// You can also specify a URL instead of calling useProxy().
// This will call /proxies/proxy.php?camanProxyUrl={url}
Caman.remoteProxy = "/proxies/proxy.php";

If no proxy is defined when a remote image is attempted to be edited, an error will be thrown.