carrierwave-meta¶ ↑

<img src=“https://secure.travis-ci.org/gzigzigzeo/carrierwave-meta.png” alt=“Build Status” /> <img src=“https://codeclimate.com/github/gzigzigzeo/carrierwave-meta.png” />

Installation¶ ↑

Add the following line to your Gemfile:

gem 'carrierwave-meta'

Usage example¶ ↑

class TestUploader < CarrierWave::Uploader::Base
  include CarrierWave::RMagick
  include CarrierWave::Meta

  process :store_meta => [{md5sum: true}]
  version :version do
    process :resize_to_fill => [200, 200]
    process :store_meta
  end
end

file = File.open('test.jpg') # JPEG 500x300, 20000 bytes
uploader = TestUploader.new
uploader.store!(file)

uploader.width        # 500
uploader.height       # 300
uploader.image_size   # [500, 300]
uploader.file_size    # 20000
uploader.content_type # "image/jpeg"
uploader.md5sum       # "fuuaasdfasdf...."

uploader.version.width        # 200
uploader.version.height       # 200
uploader.version.image_size   # [200, 200]
uploader.version.file_zie     # less than 20000
uploader.version.content_type # "image/jpeg"
uploader.version.md5sum       # nil

Saving values to database¶ ↑

Simply create database columns to hold metadata in your model’s table. Currently gem supports width, height, image_size ([width, height]), content_type, file_size and MD5 fields. Versions are supported too.

class TestModel
  attr_accessor :image_width
  attr_accessor :image_height
  attr_accessor :image_image_size
  attr_accessor :image_content_type
  attr_accessor :image_file_size
  attr_accessor :image_md5sum

  attr_accessor :image_version_width
  attr_accessor :image_version_height
  attr_accessor :image_version_image_size
  attr_accessor :image_version_content_type
  attr_accessor :image_version_file_size
  attr_accessor :image_version_md5sum
end

file = File.open('test.jpg')
model = TestModel.new
uploader = TestUploader.new(model, :image)
uploader.store!(file)

uploader.width      # 500
model.image_width   # 500
model.image_height  # 300
...

When columns are available in the model instance, metadata is stored in that columns.

Saving values into single column¶ ↑

For now, works only with ActiveRecord.

class TestModel < ActiveRecord::Base
  extend CarrierWave::Meta::ActiveRecord

  mount_uploader :image, TestUploader
  serialize :image_meta, OpenStruct
  carrierwave_meta_composed :image_meta,
    :image, image_version: [:width, :height, :md5sum]
end

model = TestModel.new
model.image.store!('test.jpg')
model.image_width         # 200
model.image_version_width # 200
model.image_meta          # {image_width: 200, image_height: 200, ...}

All you need is image_meta column, all other attributes are virtual. Note that carrierwave_meta_composed should be called after mounting uploader.

Behind the scenes¶ ↑

After the file is retrieved from store or cache metadata is recalculated unless uploader has attached model instance. If uploader has attached model instance values are read from that instance.

uploader = TestUploader.new
uploader.retrieve_from_store!('test.jpg')
uploader.version.width # 200

model = TestModel.new
model.image.store!('test.jpg')
model.image_width # 200
model.image.width # 200, actually read from image_width

model_delegate_attribute¶ ↑

Is used to synchronize data between uploader and mounted model instance. Model’s instance is used like value cache.

class DelegateTestModel
  attr_accessor :processed
  attr_accessor :a_processed
  attr_accessor :a_b_processed
end

class DelegateTestUploader < CarrierWave::Uploader::Base
  model_delegate_attribute :uploaded

  set_processed

  version :a do
    set_processed
    version :b do
      set_processed
    end
  end

  def set_processed
    self.processed = true
  end
end

model = DelegateTestModel.new
uploader = DelegateTestUploader.new(model, :image)
file = File.open('test.jpg')

uploader.store!(file)

model.processed     # true
model.a_processed   # true
model.a_b_processed # true

model.a_processed = false

uploader.processed     # true
uploader.a_processed   # false
uploader.a_b_processed # true

When model is mounted to uploader:

1. If attribute is assigned inside uploader then corresponding property

in model is also assigned.

1. If attribute is retrieved from uploader, uploader checks that value is

defined in model and returns it. Otherwise returns uploader’s instance variable.

1. If file is deleted, value becomes nil.

Otherwise acts as regular uploader’s instance variables.

This is very useful for:

Integrating CarrierWave with JCrop¶ ↑

Let implement the behavior like at this demo: deepliquid.com/projects/Jcrop/demos.php?demo=thumbnail

The uploader:

class CropUploader < SobakaUploader
  include CarrierWave::Meta

  # Crop source is a source image converted from original which could be bigger than source area (left image in the example).
  version :crop_source do
    process :resize_to_fit => [300, 300]
    process :store_meta

    # This is the cropped version of parent image. Let crop to 50x50 square.
    version :crop do
      process :crop_to => [50, 50]
    end
  end

  # Defines crop area dimensions.
  # This should be assigned before #store! and #cache! called and should be saved in the model's instance.
  # Otherwise cropped image would be lost after #recreate_versions! is called.
  # If crop area dimensions are'nt assigned, uploader calculates crop area dimensions inside the
  # parent image and creates the default image.
  model_delegate_attribute :x
  model_delegate_attribute :y
  model_delegate_attribute :w
  model_delegate_attribute :h

  # Crop processor
  def crop_to(width, height)
    # Checks that crop area is defined and crop should be done.
    if ((crop_args[0] == crop_args[2]) || (crop_args[1] == crop_args[3]))
      # If not creates default image and saves it's dimensions.
      resize_to_fill_and_save_dimensions(width, height)
    else
      args = crop_args + [width, height]
      crop_and_resize(*args)
    end
  end

  def crop_and_resize(x, y, width, height, new_width, new_height)
    manipulate! do |img|
      cropped_img = img.crop(x, y, width, height)
      new_img = cropped_img.resize_to_fill(new_width, new_height)
      destroy_image(cropped_img)
      destroy_image(img)
      new_img
    end
  end

  # Creates the default crop image.
  # Here the original crop area dimensions are restored and assigned to the model's instance.
  def resize_to_fill_and_save_dimensions(new_width, new_height)
    manipulate! do |img|
      width, height = img.columns, img.rows
      new_img = img.resize_to_fill(new_width, new_height)
      destroy_image(img)

      w_ratio = width.to_f / new_width.to_f
      h_ratio = height.to_f / new_height.to_f

      ratio = [w_ratio, h_ratio].min

      self.w = ratio * new_width
      self.h = ratio * new_height
      self.x = (width - self.w) / 2
      self.y = (height - self.h) / 2

      new_img
    end
  end

  private
  def crop_args
    %w(x y w h).map { |accessor| send(accessor).to_i }
  end
end

# Post should have :crop_source_version_x, :crop_source_version_y, :crop_source_version_h, :crop_source_version_w columns
class Post < ActiveRecord::Base
  mount_uploader CropUploader, :image
end

# Let's upload an image
post = Post.new
post.image = params[:image] # Let the uploaded file is 800x600 JPEG
post.save!

post.image.crop_source.width  # 300
post.image.crop_source.height # 200
post.image.crop_source.crop.width  # 50
post.image.crop_source.crop.height # 50

# Default crop area coordinates within the limits of big image dimensions: square at the center of an image
post.image.crop_source.crop.x # 50
post.image.crop_source.crop.y # 50
post.image.crop_source.crop.w # 200
post.image.crop_source.crop.h # 200

# Let user change the crop area with JCrop script. Pass new crop area parameters to the model.
post.crop_source_crop_x = 100
post.crop_source_crop_y = 100
post.crop_source_crop_w = 100
post.crop_source_crop_h = 100

post.save! # Crop image is reprocessed

post.image.crop_source.crop.width  # 50
post.image.crop_source.crop.height # 50

PDF/GhostScript support¶ ↑

If you want to use this plugin with PDF/PostScript files than you should install GhostScript and rebuild ImageMagick with GhostScript support:

brew install ghostscript
brew install imagemagick --with-ghostscript
gem uninstall rmagick && gem install rmagick

To switch on PDF/EPS processing you should enable GhostScript somewhere in your app’s initializer:

CarrierWave::Meta.ghostscript_enabled = true

A note about testing¶ ↑

@SergeyKishenin added specs for EPS/GhostScript files. They run for image_magick or mini_magick processor by default. To make specs work please install GhostScript as described above. To run specs WITHOUT PDF/EPS do:

PDF_EPS=false bundle exec rspec

@fschwahn added support for mini-magick. To run tests with mini-magick do:

PROCESSOR=mini_magick bundle exec rspec

@skord added support for ImageSorcery. To run specs do:

PROCESSOR=image_sorcery bundle exec rspec

To run specs against VIPS processor do:

PROCESSOR=vips bundle exec rspec

To run specs against with Fog (Amazon S3) simulation:

STORAGE=fog bundle exec rspec

TODO¶ ↑

1. I do not know how it would work with S3 and other remote storages. Should be tested.

2. Write integration guide for JCrop.

3. A notice about content-type.