JavaScript Load Image

A JavaScript library to load and transform image files.

Contents

• Demo
• Description
• Setup
• Usage
• Image loading
• Image scaling
• Requirements
• API
• Options
• Meta data parsing
• Exif parser
• IPTC parser
• License
• Credits

Demo

JavaScript Load Image Demo

Description

JavaScript Load Image is a library to load images provided as File or Blob
objects or via URL. It returns an optionally scaled and/or cropped HTML img or
canvas element. It also provides methods to parse image meta data to extract
IPTC and Exif tags as well as embedded thumbnail images and to restore the
complete image header after resizing.

Setup

Include the (combined and minified) JavaScript Load Image script in your HTML
markup:

<script src="js/load-image.all.min.js"></script>

Or alternatively, choose which components you want to include:

<script src="js/load-image.js"></script>

<script src="js/load-image-scale.js"></script>
<script src="js/load-image-meta.js"></script>
<script src="js/load-image-fetch.js"></script>
<script src="js/load-image-orientation.js"></script>

<script src="js/load-image-exif.js"></script>
<script src="js/load-image-exif-map.js"></script>

<script src="js/load-image-iptc.js"></script>
<script src="js/load-image-iptc-map.js"></script>

Usage

Image loading

In your application code, use the loadImage() function like this:

document.getElementById("file-input").onchange = function(e) {
  loadImage(
    e.target.files[0],
    function(img) {
      document.body.appendChild(img);
    },
    { maxWidth: 600 } // Options
  );
};

Image scaling

It is also possible to use the image scaling functionality with an existing
image:

var scaledImage = loadImage.scale(
  img, // img or canvas element
  { maxWidth: 600 }
);

Requirements

The JavaScript Load Image library has zero dependencies.

However, JavaScript Load Image is a very suitable complement to the
Canvas to Blob library.

API

The loadImage() function accepts a
File or
Blob object or a simple image URL
(e.g. 'https://example.org/image.png') as first argument.

If a File or
Blob is passed as parameter, it
returns a HTML img element if the browser supports the
URL API or a
FileReader object if
supported, or false.
It always returns a HTML
img element when
passing an image URL:

document.getElementById("file-input").onchange = function(e) {
  var loadingImage = loadImage(
    e.target.files[0],
    function(img) {
      document.body.appendChild(img);
    },
    { maxWidth: 600 }
  );
  if (!loadingImage) {
    // Alternative code ...
  }
};

The img element or
FileReader object returned by
the loadImage() function allows to abort the loading process by setting the
onload and onerror event handlers to null:

document.getElementById("file-input").onchange = function(e) {
  var loadingImage = loadImage(
    e.target.files[0],
    function(img) {
      document.body.appendChild(img);
    },
    { maxWidth: 600 }
  );
  loadingImage.onload = loadingImage.onerror = null;
};

The second argument must be a callback function, which is called when the
image has been loaded or an error occurred while loading the image. The callback
function is passed two arguments.
The first is either an HTML img element, a
canvas element, or an
Event object of type error.
The second is on object with the original image dimensions as properties and
potentially additional meta data:

var imageUrl = "https://example.org/image.png";
loadImage(
  imageUrl,
  function(img, data) {
    if (img.type === "error") {
      console.error("Error loading image " + imageUrl);
    } else {
      document.body.appendChild(img);
      console.log("Original image width: ", data.originalWidth);
      console.log("Original image height: ", data.originalHeight);
    }
  },
  { maxWidth: 600 }
);

Options

The optional third argument to loadImage() is a map of options:

• maxWidth: Defines the maximum width of the img/canvas element.
• maxHeight: Defines the maximum height of the img/canvas element.
• minWidth: Defines the minimum width of the img/canvas element.
• minHeight: Defines the minimum height of the img/canvas element.
• sourceWidth: The width of the sub-rectangle of the source image to draw
  into the destination canvas.
  Defaults to the source image width and requires canvas: true.
• sourceHeight: The height of the sub-rectangle of the source image to draw
  into the destination canvas.
  Defaults to the source image height and requires canvas: true.
• top: The top margin of the sub-rectangle of the source image.
  Defaults to 0 and requires canvas: true.
• right: The right margin of the sub-rectangle of the source image.
  Defaults to 0 and requires canvas: true.
• bottom: The bottom margin of the sub-rectangle of the source image.
  Defaults to 0 and requires canvas: true.
• left: The left margin of the sub-rectangle of the source image.
  Defaults to 0 and requires canvas: true.
• contain: Scales the image up/down to contain it in the max dimensions if
  set to true.
  This emulates the CSS feature
  background-image: contain.
• cover: Scales the image up/down to cover the max dimensions with the image
  dimensions if set to true.
  This emulates the CSS feature
  background-image: cover.
• aspectRatio: Crops the image to the given aspect ratio (e.g. 16/9).
  Setting the aspectRatio also enables the crop option.
• pixelRatio: Defines the ratio of the canvas pixels to the physical image
  pixels on the screen.
  Should be set to window.devicePixelRatio unless the scaled image is not
  rendered on screen.
  Defaults to 1 and requires canvas: true.
• downsamplingRatio: Defines the ratio in which the image is downsampled.
  By default, images are downsampled in one step. With a ratio of 0.5, each
  step scales the image to half the size, before reaching the target dimensions.
  Requires canvas: true.
• crop: Crops the image to the maxWidth/maxHeight constraints if set to
  true.
  Enabling the crop option also enables the canvas option.
• orientation: Transform the canvas according to the specified Exif
  orientation, which can be an integer in the range of 1 to 8 or the
  boolean value true.
  When set to true, it will set the orientation value based on the EXIF data
  of the image, which will be parsed automatically if the exif library is
  available.
  Setting the orientation also enables the canvas option.
  Setting orientation to true also enables the meta option.
• meta: Automatically parses the image meta data if set to true.
  The meta data is passed to the callback as part of the second argument.
  If the file is given as URL and the browser supports the
  fetch API, fetches
  the file as Blob to be able to parse the meta data.
• canvas: Returns the image as
  canvas element if set to
  true.
• crossOrigin: Sets the crossOrigin property on the img element for loading
  CORS enabled images.
• noRevoke: By default, the
  created object URL
  is revoked after the image has been loaded, except when this option is set to
  true.

They can be used the following way:

loadImage(
  fileOrBlobOrUrl,
  function(img) {
    document.body.appendChild(img);
  },
  {
    maxWidth: 600,
    maxHeight: 300,
    minWidth: 100,
    minHeight: 50,
    canvas: true
  }
);

All settings are optional. By default, the image is returned as HTML img
element without any image size restrictions.

Meta data parsing

If the Load Image Meta extension is included, it is also possible to parse image
meta data automatically with the meta option:

loadImage(
  fileOrBlobOrUrl,
  function(img, data) {
    console.log("Original image head: ", data.imageHead);
    console.log("Exif data: ", data.exif); // requires exif extension
    console.log("IPTC data: ", data.iptc); // requires iptc extension
  },
  { meta: true }
);

The extension also provides the method loadImage.parseMetaData, which can be
used the following way:

loadImage.parseMetaData(
  fileOrBlob,
  function(data) {
    if (!data.imageHead) {
      return;
    }
    // Combine data.imageHead with the image body of a resized file
    // to create scaled images with the original image meta data, e.g.:
    var blob = new Blob(
      [
        data.imageHead,
        // Resized images always have a head size of 20 bytes,
        // including the JPEG marker and a minimal JFIF header:
        loadImage.blobSlice.call(resizedImageBlob, 20)
      ],
      { type: resizedImageBlob.type }
    );
  },
  {
    maxMetaDataSize: 262144,
    disableImageHead: false
  }
);

Note:
Blob objects of resized images can be created via
canvas.toBlob().

The Meta data extension also adds additional options used for the
parseMetaData method:

• maxMetaDataSize: Maximum number of bytes of meta data to parse.
• disableImageHead: Disable parsing the original image head.

Exif parser

If you include the Load Image Exif Parser extension, the argument passed to the
callback for parseMetaData will contain the additional property exif if
Exif data could be found in the given image.
The exif object stores the parsed Exif tags:

var orientation = data.exif[0x0112];

It also provides an exif.get() method to retrieve the tag value via the
tag's mapped name:

var orientation = data.exif.get("Orientation");

By default, the only available mapped names are Orientation and
Thumbnail.
If you also include the Load Image Exif Map library, additional tag mappings
become available, as well as two additional methods, exif.getText() and
exif.getAll():

var flashText = data.exif.getText("Flash"); // e.g.: 'Flash fired, auto mode',

// A map of all parsed tags with their mapped names/text as keys/values:
var allTags = data.exif.getAll();

The Exif parser also adds additional options for the parseMetaData method, to
disable certain aspects of the parser:

• disableExif: Disables Exif parsing.
• disableExifThumbnail: Disables parsing of the Exif Thumbnail.
• disableExifSub: Disables parsing of the Exif Sub IFD.
• disableExifGps: Disables parsing of the Exif GPS Info IFD.

IPTC parser

If you include the Load Image IPTC Parser extension, the argument passed to the
callback for parseMetaData will contain the additional property iptc if
IPTC data could be found in the given image.
The iptc object stores the parsed IPTC tags:

var objectname = data.iptc[0x5];

It also provides an iptc.get() method to retrieve the tag value via the
tag's mapped name:

var objectname = data.iptc.get("ObjectName");

By default, the only available mapped names are ObjectName.
If you also include the Load Image IPTC Map library, additional tag mappings
become available, as well as two additional methods, iptc.getText() and
iptc.getAll():

var keywords = data.iptc.getText("Keywords"); // e.g.: ['Weather','Sky']

// A map of all parsed tags with their mapped names/text as keys/values:
var allTags = data.iptc.getAll();

The IPTC parser also adds additional options for the parseMetaData method, to
disable certain aspects of the parser:

• disableIptc: Disables IPTC parsing.

License

The JavaScript Load Image script is released under the
MIT license.

Credits

• Image meta data handling implementation based on the help and contribution of
  Achim Stöhr.
• Exif tags mapping based on Jacob Seidelin's
  exif-js library.
• IPTC parser implementation by Dave Bevan.