A Grunt task for working with image metadata profiles via ImageMagick
JavaScript
Switch branches/tags
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
tasks
test
.eslintrc.json
.gitignore
.travis.yml
Gruntfile.js
ISSUE_TEMPLATE.md
LICENSE
README.md
package.json

README.md

grunt-image-profile

A Grunt task for working with image metadata profiles via ImageMagick

Build Status Code Climate Dependency Status Built with Grunt Analytics

See ImageMagick documentation about Image Profiles for more details about what is done internally. Also about the supported formats

Getting Started

This plugin requires Grunt ~1.0 and Node.js version to be minimum of 6.9.5, which is the Long Term Support (LTS) version, and ImageMagick installed.

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-image-profile --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-image-profile');

The "image_profile" task

Overview

In your project's Gruntfile, add a section named image_profile to the data object passed into grunt.initConfig() and configure according to the multi task configuration styles.

grunt.initConfig({
  image_profile: {
    dist: {
      options: {
        // Task-specific options go here.
      },
      files: {
        // Target-specific file lists and/or options go here.
      }
    }
  },
})

Options

options.convertbin

Type: String

Default value: 'convert'

File path of the convert binary from ImageMagick. Use this option to set the path of the binary in case it is not found in the PATH of the current environment.

options.iptc

Type: Object

Example: { '2#80#Byline': 'Juga Paazmaya' }

Collection of keys and their values to be used as IPTC based profile.

options.exif

Type: Object

Example: { 'GPSLatitude': '60/1, 192322/10000, 0/1' }

EXIF data

options.save

Type: Array

Example: [ 'xmp', 'iptc' ]

Read the given profiles from the source images and write them to text files that have same name and location as the source image, while the suffix is determined by the given profile type.

Usage Examples

Please note that while most of the examples have empty options object, nothing will be written to the images in case it is used as such.

Source and destinations

The files object can be used to set the source and destination of the image files.

grunt.initConfig({
  image_profile: {
    different: {
      options: {},
      files: {
        'dest/image.jpg': 'src/image.jpg'
      }
    }
  }
})

In case the src property is used instead, the metadata will be written directly on the source image files.

grunt.initConfig({
  image_profile: {
    same_file: {
      options: {},
      src: [
        'image.jpg'
      ]
    }
  }
})

Globbing can also be used, in which case the destination can be set as a directory.

grunt.initConfig({
  image_profile: {
    different: {
      options: {},
      files: {
        'dest/': 'src/*.jpg'
      }
    },
    write_on_original: {
      options: {},
      src: [
        'path/*.jpg'
      ]
    }
  }
})

Using with IPTC Options

This example adds the given IPTC values to the JPEG files found with the source glob.

Please keep in mind that most of the keys start with 2#.

Please see IPTC Photo Metadata Standard, 2010-07-08 for possible keys.

grunt.initConfig({
  image_profile: {
    location: {
      options: {
        iptc: {
          '2#90#City': 'Helsinki',
          '2#101#Country/Primary Location Name': 'Finland',
          '2#95#Province/State': 'Uusimaa',
        }
      },
      src: ['src/**/*.jpg']
    }
  }
})

Using with EXIF options

Notice: It would seem that ImageMagick cannot write EXIF data to images at the moments. However reading is possible.

Please see EXIF specifications for further details.

Save existing profiles

With the save options it is possible to define the profiles that would be read from the given source image and saved to text files.

This example will save XMP and IPTC profiles of the source image and store them as profiles/image.xmp and profiles/image.iptc.

grunt.initConfig({
  image_profile: {
    save_profiles: {
      options: {
        save: [
          'xmp',
          'iptc'
        ]
      },
      files: {
        'profiles/': ['src/image.jpg']
      }
    }
  }
})

Contributing

"A Beginner's Guide to Open Source: The Best Advice for Making your First Contribution".

Also there is a blog post about "45 Github Issues Dos and Don’ts".

Linting is done with ESLint and can be executed with npm run lint. There should be no errors appearing after any JavaScript file changes.

Version history

  • v0.4.0 (2017-07)
    • Minimum Node.js version lifted from 4.2.0 to 6.9.5
    • main property in package.json was pointing to a wrong file
  • v0.3.1 (2016-08-11)
    • Dependencies are sure 🎩 up to date
    • Use ESLint directly without the Grunt.js plugin
  • v0.3.0 (2016-05-07)
    • Use Grunt.js v1.0.0, no smaller
    • Start using shared ESLint config #7
  • v0.2.0 (2016-02-22)
    • Ability to save existing profiles from images to text files
    • Explicitly set files to publish to npm. Ref gruntjs/gruntjs.com#65
    • Moving to ESLint #4
    • Plenty of documentation added
    • Support Grunt.js v1.0.0
  • v0.1.2 (2013-08-30)
    • Files array globbing was not working
  • v0.1.1 (2013-08-18)
    • Running tests just for IPTC usage
  • v0.1.0 (2013-08-18)
    • Initial release which can only write IPTC profiles

License

Copyright (c) Juga Paazmaya paazmaya@yahoo.com

Licensed under the MIT license.