Smartcrop.js Deployment and Usage Guide

Prerequisites

• Runtime: Node.js (for CLI usage) or a modern web browser with Canvas API support
• Package Manager: npm (for installation via npm)
• Browser Support: Canvas API support (see caniuse.com/canvas)
• Promises: Native Promises support or a Promise polyfill for older browsers
• Optional: Face detection libraries (e.g., tracking.js, opencv.js) for enhanced cropping

Installation

Via npm

npm install smartcrop

Manual Download

Download the library directly from the GitHub repository:

wget https://raw.githubusercontent.com/jwagner/smartcrop.js/master/smartcrop.js

Promise Polyfill (for older browsers)

If you need to support older browsers without native Promise support:

npm install promise-polyfill

Configuration

Setting Custom Promise Implementation

If you want to use a custom Promise implementation (recommended: Bluebird):

smartcrop.Promise = require('bluebird');

Default Configuration Options

The library uses these default settings:

smartcrop.DEFAULTS = {
  width: 0,
  height: 0,
  aspect: 0,
  cropWidth: 0,
  cropHeight: 0,
  detailWeight: 0.2,
  skinColor: [0.78, 0.57, 0.44],
  skinBias: 0.01,
  skinBrightnessMin: 0.2,
  skinBrightnessMax: 1.0,
  skinThreshold: 0.8,
  skinWeight: 1.8,
  saturationBrightnessMin: 0.05,
  saturationBrightnessMax: 0.9,
  saturationThreshold: 0.4,
  saturationBias: 0.2,
  saturationWeight: 0.1,
  scoreDownSample: 8,
  step: 8,
  scaleStep: 0.1,
  minScale: 0.9,
  maxScale: 1.0,
  edgeRadius: 0.4,
  edgeWeight: -20.0,
  outsideImportance: -0.5,
  ruleOfThirds: true,
  prescale: true,
  canvasFactory: null,
  debug: false
};

Build & Run

Browser Usage

<script src="smartcrop.js"></script>
<script>
  smartcrop.crop(image, { width: 100, height: 100 }).then(function(result) {
    console.log(result);
  });
</script>

Node.js Usage

const smartcrop = require('smartcrop');

smartcrop.crop(image, { width: 100, height: 100 }).then(function(result) {
  console.log(result);
});

Command Line Interface

Use the smartcrop-cli for command line operations:

npm install -g smartcrop-cli
smartcrop-cli input.jpg output.jpg --width 100 --height 100

Deployment

Static Website Deployment

Smartcrop.js can be deployed as part of any static website. Simply include the script in your HTML:

<script src="smartcrop.js"></script>

Node.js Application Deployment

For Node.js applications, include smartcrop as a dependency in your package.json and deploy as usual.

Recommended Platforms

• Static Hosting: Netlify, Vercel, GitHub Pages
• Node.js: Heroku, Railway, AWS Lambda
• Docker: Containerize your application with the smartcrop dependency

Troubleshooting

Common Issues

1. "No native promises and smartcrop.Promise not set" error

// Solution: Set a Promise implementation
smartcrop.Promise = Promise; // or require('bluebird')

2. Cross-origin image issues

// Solution: Use images from the same origin or configure CORS headers

3. Performance issues with large images

// Solution: Adjust the scoreDownSample option
smartcrop.crop(image, { scoreDownSample: 16 });

4. Face detection not working

// Solution: Integrate a face detection library like tracking.js
// See the test bed for examples: https://29a.ch/sandbox/2014/smartcrop/examples/testbed.html

5. Module loading issues

// Solution: Smartcrop supports CommonJS, AMD, and global exports
// Ensure you're using the correct format for your environment

Testing

Run the test suite to verify functionality:

npm test

Browser Compatibility

For older browsers, ensure you include a Promise polyfill and test Canvas API support.