How to use

How to use CamanJS

Building CamanJS Yourself

CamanJS is built into the dist folder. The copies of CamanJS that are already in the folder are kept up-to-date; however, if you make any modifications to CamanJS and wish to combine all of the plugins and minify the code, you will have to re-build it yourself. Building CamanJS also runs JSHint on the code to check for syntax and formatting errors, which are reported at build time.

Building CamanJS requires NodeJS to be installed. To build, simply run:

node Makefile.js

The copies of CamanJS that are in the dist folder will be overwritten with the newly built copies. The 'full' copies include all of the plugins, while the non-full copies are simply the core library.

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();
});

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

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. You can also specify a URL instead of calling useProxy().
Caman.remoteProxy = Caman.useProxy('php');

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