loading...
blog Thoughts, updates, and advice...

Image Cutter

An open source javascript image cropping plug-in

Image Cutter

Posted January 17, 2014

We are proud to present Image Cutter!
Image Cutter is a javascript plug-in that creates a user-interface for cropping images. It is free, open, flexible, easy-to-use, cross-browser friendly, touch friendly, and has no dependencies.



Contents


Features
License and Download
How to Use Image Cutter
Options
Methods
Contact



Features

  • Image Cutter is easy to use, even for Javascript novices
  • Image Cutter has a huge selection of options and methods available, including minimum and maximum heights and widths, fixed aspect ratios, starting selections, and zoom functionality.
  • Image Cutter has been tested and works great on Chrome, FF, Safari, Opera, and IE6+*
  • Image Cutter works great on touch screens**
  • Image Cutter has no code dependencies - no need to install jQuery or any other javascript library to use. There are also no required CSS or image files to attach
  • Image Cutter has been coded with compatibility in mind - no matter what other code you have, Image Cutter should play well with others
  • Image Cutter is easily templatable. Nearly every aspect of the interface allows you to attach your own CSS classes, allowing you to completely dictate the look and feel on your site
  • Image Cutter is free and open source. Want to use it for a personal project? Great! Want to use it for a commercial project without crediting us? No problem! Want to tweak the code for your own purposes? We have fully commented and organized code that will make it easy to do. Want to print out the source code on toilet paper? Why not?

* Some of the character codes that create the default resizing arrows are missing on Internet Explorer 6. However, you are still able to attach your own classes to each arrow, so can simply replace those arrows with whatever fits your project.
** Tested on iOS Safari and Android Chrome



License & Download

Image Cutter is © 2013 by Steven Riche and Joust Multimedia with the MIT License.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Download image_cutter.js   (v1.0 - Full Version - 69KB)

Download image_cutter.min.js   (v1.0 - Minified Version - 27KB)

Download ZIP archive    (v1.0 - Contains full and minified versions, with examples - 73KB)



How to Use Image Cutter

If you have a web application that needs to allow a user to crop an image, this requires a number of steps:

1) Choose an image (whether uploaded by the user or already on your server) and display that image on the website

2) Give the user an intuitive way of deciding the height, width, left offset, and top offset of the image to crop

3) Send those values back and use a serverside language like PHP or ASP to crop the image.

Image Cutter is a javascript library that adds a user-interface to an image (step #2 above), allowing the user to select an area to crop.
The library works by adding HTML elements over the image to create the user-interface, and then creating hidden input fields that track the coordinates of the user's selection.
You can add Image Cutter to your site with just a few easy steps.

First, you will need to download the javascript file, and attach it to your page.

<!-- Somewhere in your code, preferably in your header -->
  <script type="text/javascript" src="path/to/image_cutter.js"></script>

Then, you will need to place the image you want to crop inside of an empty DIV. Give that DIV an ID.

<!-- Somewhere in your HTML -->
  <div id="my_image_cutter_id">>
    <img src="my_image.jpg" />
  </div>

Finally, place the following code in your document. You will need to either place it after the image, or in an event handler that runs when the page finishes loading.

  <script type="text/javascript">
    // Somewhere later in your code, like in your footer, or in an onLoad function
    ImageCutter({
      'id' : 'my_image_cutter_id', // Enter your DIV id here
      'action' : 'image_crop_function.php' // Enter the path to your server side function here
    });
  </script>

And that is all you need for the default version (with some classes applied to the buttons), as seen below (click and drag to select an area):

You can click the Crop button to see the form data that is set to the server, or click the zoom in and out to make the image larger or smaller (while still preserving the selection).



Options

While the above example is all that is necessary to run Image Cutter, there are a ton of additional options.

Option Default Type Description
'id' 'image_cutter' string This should be the ID of the DIV surrounding your image
'action' 'index.php' string This is the path to the serverside function used to crop the image
'callbackFn' '' string This is a function name (without the '( )' ) that will be called every time the user makes or changes a selection. This function will be passed an object containing all of the width, height, x, and y data (as obj.width, obj.height, obj.x1, and obj.y1)
'initCallbackFn' '' string This is a function name (without the '( )' ) that will be called when Image Cutter is first initialized. This function will NOT be passed any objects
'startingSelection' false true / false Set this to true if you want to automatically select a starting area when Image Cutter is initialized
'startingLeft' 0 number If having a starting selection, the left attribute of the selection, in pixels
'startingTop' 0 number If having a starting selection, the top attribute of the selection, in pixels
'startingWidth' 100 number or 'full' If having a starting selection, the width attribute of the selection, in pixels. If larger than the available width, then selects the full available width. If set to 'full', then it sets the width to the full remaining area
'startingHeight' 100 number or 'full' If having a starting selection, the height attribute of the selection, in pixels. If larger than the available height, then selects the full available height. If set to 'full', then it sets the height to the full remaining area
'startingAll' false true / false If true, this overrides all other starting selection options and selects the entire area
'fixedWidth' 0 number Forces selections to be a fixed width, and overrides 'startingWidth'. Set to 0 to disable
'fixedHeight' 0 number Forces selections to be a fixed height, and overrides 'startingHeight'. Set to 0 to disable
'fixedRatio' 0 number or fraction Forces selections to be a fixed aspect ratio, like 3px wide for every 2px tall. This is the value of width / height, and can be given as either a fraction (like 3/2) or as a decimal (like 1.5)
'submitBtn' true true / false If true, automatically adds a submit button to submit the selection coordinates to the serverside function given in the 'action' option. You can disable this and create your own way to handle the coordinates (see the Methods section)
'submitValue' 'Crop' string This is the title on the 'Crop' button (if 'submitBtn' is set to true)
'submitClass' '' string This is an optional CSS class you can add to the 'Crop' button (if 'submitBtn' is set to true)
'clearBtn' 'none' 'none' / 'clear' / 'full' If set to 'clear', adds a button that clears the selection when clicked. If set to 'full', adds a button that selects the entire image when clicked. If 'none', does not add a 'Clear' button
'clearBtnValue' 'Clear' string This is the title on the 'Clear' button (if 'clearBtn' is set to 'clear' or 'full')
'clearBtnClass' '' string This is an optional CSS class you can add to the 'Clear' button (if 'clearBtn' is set to 'clear' or 'full')
'zoomBtn' true true / false If true, generates Zoom In button and Zoom Out button, allowing users to enlarge or shrink the image without affecting the selected area
'zoomInClass' '' string This is an optional CSS class you can add to the 'Zoom In' button (if 'zoomBtn' is set to true)
'zoomOutClass' '' string This is an optional CSS class you can add to the 'Zoom Out' button (if 'zoomBtn' is set to true)
'zoomInValue' 'Zoom In' string This is the text that will appear on the 'Zoom In' button (if 'zoomBtn' is set to true)
'zoomOutValue' 'Zoom Out' string This is the text that will appear on the 'Zoom Out' button (if 'zoomBtn' is set to true)
'zoomInAmount' 20 number
(between 0 and 100)
This is the percentage (compared with the current size) that the image will enlarge when 'Zoom In' is clicked
'zoomOutValue' 25 number
(between 0 and 100)
This is the percentage (compared with the current size) that the image will shrink when 'Zoom Out' is clicked
'autoScale' 'none' 'none' / 'scaledown' / 'fit' If set to 'fit', the image will automatically be resized to fit inside the next parent element that has a height or width specified. If no parent elements have a height or width specified, the image will resize to fit in the user's browser window. If set to 'scaledown', the image will only resize if it is too large for the parent element or browser window
'shadowBoxColor' '#000000' hex color value, as string This is the color value for the overlay over the image
'shadowBoxOpacity' 0.5 number
(between 0 and 1)
The opacity of the overlay over the image
'shadowBoxClass' '' string This is an optional CSS class you can add to the image overlay
'selectionClass' '' string This is an optional CSS class you can add to the selection area DIV
'swapArrows' false true / false If set to true, this will replace the default behavior of creating SPANs with HTML character codes for resizing arrows, and will instead create DIVs for each arrow. Use this to make styling easier if you would like to design your own resizing arrows
'arrowClass' '' string Optional CSS class to apply to all eight resizing arrows
'arrowNClass' '' string Optional CSS class to apply to only the North arrow
'arrowNEClass' '' string Optional CSS class to apply to only the Northeast arrow
'arrowEClass' '' string Optional CSS class to apply to only the East arrow
'arrowSEClass' '' string Optional CSS class to apply to only the Southeast arrow
'arrowSClass' '' string Optional CSS class to apply to only the South arrow
'arrowSWClass' '' string Optional CSS class to apply to only the Southwest arrow
'arrowWClass' '' string Optional CSS class to apply to only the West arrow
'arrowNWClass' '' string Optional CSS class to apply to only the Northwest arrow


Methods

In addition to the various options available, you might want to create your own custom scripts to handle coordinates, zoom in or out, clear the selection area, etc. You can do this easily by naming the ImageCutter object as a variable when you initialize Image Cutter. So, instead of this:

  <script type="text/javascript">
    // Somewhere later in your code, like in your footer, or in an onLoad function
    ImageCutter({
      'id' : 'my_image_cutter_id', // Enter your DIV id here
      'action' : 'image_crop_function.php' // Enter the path to your server side function here
    });
  </script>

You can do something like this:

  <script type="text/javascript">
    // Somewhere later in your code, like in your footer, or in an onLoad function
    var my_variable_name = ImageCutter({
      'id' : 'my_image_cutter_id', // Enter your DIV id here
      'action' : 'image_crop_function.php' // Enter the path to your server side function here
    });
  </script>

You can then simply call one of the following methods with your declared variable like this:

  <script type="text/javascript">
    // Somewhere in your code after you have initiated 'my_variable_name'
    my_variable_name.clear();
  </script>

The following methods are currently available:


add_field(name, value)

name - string - The name you want attached to your added hidden input
value - string / number - The value you want in your hidden input field
This adds your own custom hidden field to the hidden form that sends image coordinates to the server. If you need to add custom information to your serverside code (e.g. the user who cropped the image), but still use the default form building behavior, then use this function.

clear()

This function clears the current selection.

full()

This function selects the entire image.

returnX()

This function returns the X pixel value of the top left corner of the current selection. This is set to 0 if there have been no selection yet, and is set to an empty string after a selection has been made.

returnY()

This function returns the Y pixel value of the top left corner of the current selection. This is set to 0 if there have been no selection yet, and is set to an empty string after a selection has been made.

returnWidth()

This function returns the width of the current selection in pixels. This is set to the width of the image if there have been no selection yet, and is set to an empty string after a selection has been made.

returnHeight()

This function returns the height of the current selection in pixels. This is set to the height of the image if there have been no selection yet, and is set to an empty string after a selection has been made.

returnZoom()

This function returns a number that represents the current zoom of the image. 1 represents the image is displayed at its current size. A 2 would mean the height and width of the image are displayed twice the size as the original image, while 0.5 would mean the height and width of the image are displayed as half the size of the original image.

set(x, y, w, h)

x - number - The x coordinate in pixels where you want to place the top left corner of the selection
y - number - The y coordinate in pixels where you want to place the top left corner of the selection
w - number - The width, in pixels, that you would like to set the selection. If the width is wider than the remaining area, then the width will be set to the widest possible area
h - number - The height, in pixels, that you would like to set the selection. If the height is taller than the remaining area, then the height will be set to the tallest possible area
This function allows you to manually set a selection by passing in all of the coordinates yourself.

zoomIn(num)

num - number - The percentage you want to enlarge the displayed image (use 25 for 25%, not 0.25)
This function allows you to replicate the Zoom In button with your own value passed in as the amount to zoom in.

zoomOut(num)

num - number - The percentage you want to shrink the displayed image (use 25 for 25%, not 0.25)
This function allows you to replicate the Zoom Out button with your own value passed in as the amount to zoom out.

destroy(return_size)

return_size - true / false - (Optional) If true, then the image will return to its original size if it had been enlarged or shrunk.
This function completely removes all of the ImageCutter object, including removing the shadow box, cropping area, hidden fields, and buttons. It also gives the option to set the image back to its original size if it had been zoomed.



Contact

Have a question? Found a bug? Have some feedback or ideas for additional features?
Drop us a line at code @ joustmultimedia.com.

Written By:

Steven Riche

Steven Riche
Lead Developer
View Other Entries

Get Social

Tags

Recent Blog Entries

Steven Riche

Get Fluent in the Web - HTML5

So you are thinking about getting on-board this new-fangled World Wi ...

Steven Riche

Image Cutter

Image Cutter is a javascript plug-in that creates a user-interface f ...

Steven Riche

JS Animation that Works

HTML is the language the web is built in, and it is kind of a strang ...

Charlotte Katelyn

The Personality of Color

Every color has a personality. So before you start just picking what ...

Charlotte Katelyn

The Art of Combining Fonts

So you've found the font for your design. It's perfect. The ...

Return to Blog Menu