Basic Usage

Using CamanJS is extremely simple, but also very flexible. All of the functionality is accessed by calling the Caman() function.

One very important thing to note: due to browser security restrictions, CamanJS can only modify images that come from the same domain as the page in which it's loaded unless you specify a proxy (more info below).

First, we need to include the appropriate Javascript files for Caman:

<!-- Either include the full CamanJS code including plugins -->
<script type="text/javascript" src="caman.full.min.js"></script>

<!-- Or include the core library and only the plugins you want to use -->
<script type="text/javascript" src="caman.min.js"></script>
<script type="text/javascript" src="plugins/camera.js"></script>
<script type="text/javascript" src="plugins/presets.js"></script>

Now that we've loaded the library, we can use it in any of the various ways shown below:

Loading an Image into a Canvas via URL

This method assumes you already have a canvas element in the page, and you would like to load an image via URL into the canvas for editing with CamanJS.

Caman("path/to/image.jpg", "#canvas-id", function () {
	// manipulate image here
	this.brightness(5).render();
});

Replacing an Image with Canvas

If you have an image element on the page you would like to modify directly, this method replaces that image with an identically-sized canvas element. If you don't modify the image at all, it will look identical to the user since CamanJS automatically paints the image contents to the canvas. Again, this only works on images that are on the same domain as the webpage.

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

Loading onto a Canvas without an Image

This is especially useful if you have a canvas element that already has some data on it that you want to modify. For example, you could capture an image from a webcam onto a canvas element, then modify that canvas using Caman.

Caman("#canvas-id", function () {
	// manipulate canvas here
	this.brightness(5).render();
});

Editing a Remote Image

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.useProxy('php');

// You can also specify a URL instead of calling useProxy()
Caman.remoteProxy = "/path/to/proxy";

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

Basic Workflow

While CamanJS is flexible, there is a basic workflow you will probably find yourself using. Some things are optional, some are not.

Caman(/* loading arguments here */, function () {
	// In this callback function we will do our image modification.

	// We can either call each filter separately:
	this.brightness(5);
	this.contrast(10);
	
	// Or we can chain them together like this. Both are equivalent
	// in the end.
	this
		.sepia(40)
		.saturation(5);
		
	// In order to update the image to show the changes, we need
	// to make a call to render().  This is what signals CamanJS to
	// begin making the modifications to the image.
	//
	// NOTE: render() runs asynchronously, so it takes an optional
	// callback, which is fired when rendering completes.
	this.render(function () {
		console.log("Finished!");
	});
});

Referencing the Caman Object

When you call the Caman() function to load CamanJS, it returns a Caman.manip object. This object can be used to modify the image further outside of the original callback function. This is probably best shown with an example:

// Save the object returned from Caman()
var camanImg = Caman("#image-id", function () {
	// Here we can modify the image if we want, but beware
	// of race conditions if you call render(). This callback
	// function is actually optional.
	
	this.brightness(10);
});

// Now that we have a reference to the Caman.manip object returned
// from calling Caman(), we can further modify the image.
camanImg
	.contrast(5)
	.sepia(40)
	.render();
	
// Alternatively, we can also do this if we don't save the return object
// from Caman()
Caman("#image-id")
	.contrast(5)
	.sepia(40)
	.render();

One thing to be careful of, however, is that rendering is performed asynchronously. Before modifying the image again you will want to make sure that any previous rendering has completed.