= carrierwave-meta

{<img src="https://secure.travis-ci.org/gzigzigzeo/carrierwave-meta.png" alt="Build Status" />}[http://travis-ci.org/gzigzigzeo/carrierwave-meta]
{<img src="https://codeclimate.com/github/gzigzigzeo/carrierwave-meta.png" />}[https://codeclimate.com/github/gzigzigzeo/carrierwave-meta]

= 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.
2. If attribute is retrieved from uploader, uploader checks that value is
defined in model and returns it. Otherwise returns uploader's instance variable.
3. 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: http://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.