mpo_tools 0.0.1

data/.rvmrc

@@ -0,0 +1 @@
+rvm ruby-1.9.2-p290@mpo_tools

data/Gemfile

@@ -0,0 +1,2 @@
+source :rubygems
+gemspec

data/Gemfile.lock

@@ -0,0 +1,33 @@
+PATH
+  remote: .
+  specs:
+    mpo_tools (0.0.1)
+      rmagick
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    colored (1.2)
+    diff-lcs (1.2.5)
+    rake (10.1.1)
+    rake-notes (0.2.0)
+      colored
+      rake
+    rmagick (2.13.2)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.7)
+    rspec-expectations (2.14.5)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.5)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  mpo_tools!
+  rake
+  rake-notes
+  rspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Will Brown
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,84 @@
+# MPO Tools
+
+## Synopsis
+This gem provides some simple utility methods for working with MPO format 3D image files. This file format is used in 3D cameras such as the [Nintendo 3DS](http://en.wikipedia.org/wiki/Nintendo_3ds) and the [Fujifilm FinePix W3](http://en.wikipedia.org/wiki/Fujifilm_FinePix_Real_3D_W3). 
+
+ImageMagick does not support this file type and, as a consequence, I found the format difficult to work with when I needed to process images in bulk (for example when creating 3D timelapses). This gem is intended to make that process easier.
+
+The gem can be used to extract the EXIF data or the left and right images themselves from an MPO file. It can also be used to convert MPO files into a number of different (2D display friendly) viewing formats.
+
+Supported output formats include:
+
+| Name       | Format        | Description                                    |
+| ---------- | ------------- | ---------------------------------------------- |
+| Stereogram | `:stereo`     | left/right side by side                        |
+| Cross-eyed | `:cross_eyed` | right/left side by side                        |
+| Analglyph  | `:analglyph`  | red and blue (for use with coloured glasses)   |
+| Wiggle GIF | `:wiggle`     | animated gif (cycles between left/right image) |
+
+Also included is a binary for converting MPO files on the command line.
+
+The mechanism for extracting the left and right images from the MPO is based on the exiftool usage example described in [this article](http://brainwagon.org/2009/11/04/fujifilm-real-3d-w1-camera/) by Mark VandeWettering.
+
+
+## Install the gem
+
+Install it with [RubyGems](https://rubygems.org)
+
+```ruby
+gem install mpo_tools
+```
+
+or add this to your Gemfile if you use [Bundler](http://gembundler.com)
+
+```ruby
+gem 'mpo_tools'
+```
+
+MPO Tools is dependent on [exiftool](http://www.sno.phy.queensu.ca/~phil/exiftool/), to install this on Ubuntu run
+
+    sudo apt-get install libimage-exiftool-perl
+
+## Getting Started
+
+Here's an example of how you might convert a whole directory of MPO image files to analglyphs and resize them to 320x240 pixels.
+
+```ruby
+require 'mpo_tools'
+path = '/home/bob/3d_pictures/*.MPO'
+dest = '/home/bob/analglyphs/'
+Dir.glob(path).each do |mpo|
+  # path_to_mpo, output_path, format, scale/resolution
+  MpoTools.convert mpo, dest, :analglyph, [320,240]
+end
+```
+
+For information on how to use the command line tool run
+
+    $ mpo_convert -h
+
+For more information please take a look at the rdoc documentation.
+
+## License
+Copyright (c) 2014 Will Brown
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,7 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+require 'rake/notes/rake_task'
+
+desc "run RSpec tests"
+RSpec::Core::RakeTask.new(:test)

data/bin/mpo_convert

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# Encoding: utf-8
+# Name: MPO Convert
+# Author: Will Brown
+# Created: 2014-02-17
+# Description:
+#   Utility for converting .mpo 3D image files to other 3D image formats
+require 'pathname'
+require 'optparse'
+$LOAD_PATH << Pathname.new(__FILE__).realpath.parent.parent + 'lib'
+require 'mpo_tools'
+
+source, destination, format, scale = nil, nil, :stereo, 1
+OptionParser.new do |opts|
+  opts.banner = 'Usage: mpo_convert -s pics/sample.mpo -d converted/ -a -c 0.5'
+  opts.on('-s', '--source PATH', 'location of disk of the .mpo file') {|s| source = s }
+  opts.on('-d', '--destination PATH', 'output location of the new file')  {|d| destination = d }
+  opts.on('-c', '--scale SCALE', 'The size of the outputted image')  {|c| scale = c.to_f }
+  opts.on('-t', '--stereo', 'Output as stereo (default)') { format = :stereo }
+  opts.on('-x', '--cross-eyed', 'Output as cross-eyed') { format = :cross_eyed }
+  opts.on('-w', '--wiggle', 'Output as wiggle gif') { format = :wiggle }
+  opts.on('-a', '--analglyph', 'Output as analglyph') { format = :analglyph }
+  opts.on('-h', '--help', 'this message') { puts opts; exit 1 }
+end.parse!
+
+begin
+  MpoTools.convert(source, destination, format, scale)
+rescue MpoError => e
+  abort e.message
+end

data/lib/mpo_tools.rb

@@ -0,0 +1,137 @@
+['pathname', 'json', 'RMagick'].each { |lib| require lib }
+
+# Raised when the MPO file cannot be parsed or converted
+class MpoError < StandardError; end
+
+# The core library. This module provides methods for converting and extracing 
+# data from MPO format 3D photographs. It uses imagemagick and exiftool to do
+# this, so both libraries must be installed on your system for this code to work
+module MpoTools
+
+  # List of supported output formats
+  FORMATS = [:stereo, :cross_eyed, :wiggle, :analglyph]
+
+  # Convert the provided MPO file into the desired format
+  # ==== Parameters
+  # [source] The location of disk of the .mpo file
+  # [destination] The desired output location of the new file (Optional)
+  # [format] The desired output format. A list of valid formats can be found in
+  #   the +FORMATS+ constant (Optional, defaults to :stereo)
+  # [scale] The size of the outputted image. This can be provided as a scale
+  #   with 1 representing the original size. Alternatively an array can be
+  #   passed in with the format [x_size, y_size]
+  #
+  # ==== Returns
+  # * The location on disk of the newly created output file.
+  #
+  # ==== Raises
+  # * MpoError - Raised when the provided source file cannot be converted
+  def self.convert(source, destination=nil, format=FORMATS.first, scale=1)
+    raise MpoError.new "Invalid format: #{format}" if !FORMATS.include?(format)
+    source, destination = validate_paths source, destination, format
+    left, right = extract_images source
+    left, right = scale_images left, right, scale unless scale == 1
+    send "output_as_#{format}", left, right, destination
+  end
+
+  # Reads the source MPO file and returns a hash of exif data
+  # ==== Parameters
+  # [source] The location on disk of the .mpo file
+  #
+  # ==== Returns
+  # * A ruby hash containing the file's exif meta data
+  #
+  # ==== Raises
+  # * MpoError - Raised when exif data cannot be read from the source or when
+  #     the exiftool application has not been installed
+  def self.exif_data(source)
+    exif = `exiftool -u -d "%Y-%m-%d %H:%M:%S" -json #{source}`
+    return JSON.parse(exif).first
+  rescue Errno::ENOENT => e
+    raise MpoError.new "Please install 'exiftool' on your machine.\n  \"sudo apt-get install libimage-exiftool-perl\" on Ubuntu"
+  rescue JSON::ParserError => e
+    raise MpoError.new 'Unable to read exif data'
+  end
+  
+  # Extracts two images from the MPO file
+  # ==== Parameters
+  # [source] The location on disk of the .mpo file
+  #
+  # ==== Returns
+  # * The left eye image in +Magick::Image+ format
+  # * The right eye image in +Magick::Image+ format
+  #
+  # ==== Raises
+  # * MpoError - Raised when two images cannot be created based on the provided
+  #     source file or when the exiftool application has not been installed
+  def self.extract_images(source)
+    left = Magick::Image.from_blob(`exiftool -trailer:all= #{source} -o -`)[0]
+    right = Magick::Image.from_blob(`exiftool #{source} -mpimage2 -b`)[0]
+    return left, right
+  rescue Errno::ENOENT => e
+    raise MpoError.new "Please install 'exiftool' on your machine.\n  \"sudo apt-get install libimage-exiftool-perl\" on Ubuntu"
+  rescue Magick::ImageMagickError => e
+    raise MpoError.new 'Unable to extract images'
+  end
+
+  private
+
+  # Resizes both left and right images
+  def self.scale_images left, right, scale
+    if scale.is_a?(Array) && scale.length == 2
+      return left.scale(*scale), right.scale(*scale)
+    elsif scale.is_a?(Float) || scale.is_a?(Integer)
+      return left.scale(scale), right.scale(scale)
+    else
+      raise MpoError.new 'Invalid scale'
+    end
+  end
+
+  # Outputs the 3D image in stereo, left image on the left and right image
+  # on the right
+  def self.output_as_stereo(left, right, destination)
+    destination = "#{destination}.jpg" unless destination =~ /.jpg$/i
+    Magick::ImageList.new.push(left, right).append(false).write(destination)
+    return destination
+  end
+
+  # Creates a reversed stereo image, which can be viewed by going cross-eyed
+  def self.output_as_cross_eyed(left, right, destination)
+    output_as_stereo right, left, destination
+  end
+
+  # Outputs as an analglyph that can be viewed with coloured glasses
+  def self.output_as_analglyph(left, right, destination)
+    destination = "#{destination}.jpg" unless destination =~ /.jpg$/i
+    left.stereo(right).write(destination)
+    return destination
+  end
+
+  # Outputs as a 'wiggle' gif. An animated gif that rapidly cycles between
+  # left and right image
+  def self.output_as_wiggle(left, right, destination)
+    destination = "#{destination}.gif" unless destination =~ /.gif$/i
+    gif = Magick::ImageList.new.push(left, right)
+    gif.delay = 5
+    gif.write(destination)
+    return destination
+  end
+
+  # Validates the provided source and destination paths, builds the destination
+  # path if a full file path has not been provided
+  def self.validate_paths(source, destination, format)
+    raise MpoError.new('Source not an mpo') unless source =~ /\.mpo$/i
+    raise MpoError.new('Source not found') unless File.exists?(source)
+    source = Pathname.new(source)
+    if destination && File.directory?(destination)
+      source_name = source.basename.to_s.gsub(/\.mpo$/, '')
+      destination = Pathname.new(destination) + "#{source_name}_#{format}"
+    elsif destination
+      destination = Pathname.new(destination)
+    else
+      stripped_source = source.realpath.to_s.gsub(/\.mpo$/, '')
+      destination = Pathname.new(stripped_source + "_#{format}")
+    end
+    return source.realpath.to_s, destination.to_s
+  end
+end

data/lib/version.rb

@@ -0,0 +1,3 @@
+module MpoTools
+  VERSION = '0.0.1'
+end

data/mpo_tools.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ['Will Brown']
+  gem.email         = ['mail@willbrown.name']
+  gem.description   = 'Tools for working with MPO format stereoscopic 3D images'
+  gem.summary       = 'Tools for working with MPO format stereoscopic 3D images'
+  gem.homepage      = 'https://github.com/rawls/mpo_tools'
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "mpo_tools"
+  gem.require_paths = ["lib"]
+  gem.version       = MpoTools::VERSION
+  gem.platform      = Gem::Platform::RUBY
+  gem.date          = '2014-02-07'
+  gem.license       = 'MIT'
+
+  gem.required_ruby_version = '>= 1.9.2'
+  gem.extra_rdoc_files = ['README.md']
+
+  gem.add_runtime_dependency 'rmagick'
+
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'rake-notes'
+end

data/spec/mpo_tools_spec.rb

@@ -0,0 +1,103 @@
+require 'mpo_tools'
+
+describe MpoTools do
+  before :all do
+    path = Pathname.new(__FILE__).realpath.parent + 'example_data' + 'sample.mpo'
+    @source = path.realpath.to_s
+    @destination = '/tmp/'
+  end
+
+  describe '.convert' do
+    
+    context 'format is :stereo' do
+      it 'exports a jpg image' do
+        output_file = MpoTools.convert @source, @destination, :stereo, 1
+        img = Magick::Image.read(output_file).first
+        x_size, y_size = img.columns, img.rows
+        exif = MpoTools.exif_data @source
+        x_size.should eq(exif['ImageWidth']*2)
+        y_size.should eq(exif['ImageHeight'])
+        FileUtils.rm output_file if File.exists?(output_file)
+      end
+    end
+    
+    context 'format is :cross_eyed' do
+      it 'exports a jpg image' do
+        output_file = MpoTools.convert @source, @destination, :cross_eyed, 1
+        img = Magick::Image.read(output_file).first
+        x_size, y_size = img.columns, img.rows
+        exif = MpoTools.exif_data @source
+        x_size.should eq(exif['ImageWidth']*2)
+        y_size.should eq(exif['ImageHeight'])
+        FileUtils.rm output_file if File.exists?(output_file)
+      end
+    end
+    
+    context 'format is :analglyph' do
+      it 'exports a jpg image' do
+        output_file = MpoTools.convert @source, @destination, :analglyph, 1
+        img = Magick::Image.read(output_file).first
+        x_size, y_size = img.columns, img.rows
+        exif = MpoTools.exif_data @source
+        x_size.should eq(exif['ImageWidth'])
+        y_size.should eq(exif['ImageHeight'])
+        FileUtils.rm output_file if File.exists?(output_file)
+      end
+    end
+    
+    context 'format is :wiggle' do
+      it 'exports a gif image' do
+        output_file = MpoTools.convert @source, @destination, :wiggle, 1
+        img = Magick::Image.read(output_file).first
+        x_size, y_size = img.columns, img.rows
+        exif = MpoTools.exif_data @source
+        x_size.should eq(exif['ImageWidth'])
+        y_size.should eq(exif['ImageHeight'])
+        FileUtils.rm output_file if File.exists?(output_file)
+      end
+    end
+    
+    context 'scale is .5' do
+      it 'exports an image 50% of the size of the original' do
+        output_file = MpoTools.convert @source, @destination, :stereo, 0.5
+        img = Magick::Image.read(output_file).first
+        x_size, y_size = img.columns, img.rows
+        exif = MpoTools.exif_data @source
+        x_size.should eq(exif['ImageWidth'])
+        y_size.should eq(exif['ImageHeight']/2)
+        FileUtils.rm output_file if File.exists?(output_file)
+      end
+    end
+    
+    context 'scale is [640,480]' do
+      it 'exports an image with a resolution of 640x480' do
+        output_file = MpoTools.convert @source, @destination, :stereo, [640,480]
+        img = Magick::Image.read(output_file).first
+        x_size, y_size = img.columns, img.rows
+        x_size.should eq(1280)
+        y_size.should eq(480)
+        FileUtils.rm output_file if File.exists?(output_file)
+      end
+    end
+
+  end
+
+  describe '.exif_data' do
+    it 'correctly interprets the EXIF data of .mpo files' do
+      exif = MpoTools.exif_data @source
+      exif["ImageWidth"].should eq(640)
+      exif["ImageHeight"].should eq(480)
+      exif["ColorSpace"].should eq("sRGB")
+      exif["NumberOfImages"].should eq(2)
+    end
+  end
+  
+  describe '.extract_images' do
+    it 'returns two RMagick::Image objects' do
+      left, right = MpoTools.extract_images @source
+      left.should be_a(Magick::Image)
+      right.should be_a(Magick::Image)
+    end
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,4 @@
+require 'pathname'
+require 'fileutils'
+require 'RMagick'
+require_relative '../lib/mpo_tools'

metadata

@@ -0,0 +1,128 @@
+--- !ruby/object:Gem::Specification
+name: mpo_tools
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Will Brown
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-02-07 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rmagick
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake-notes
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Tools for working with MPO format stereoscopic 3D images
+email:
+- mail@willbrown.name
+executables:
+- mpo_convert
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- .rvmrc
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- Rakefile
+- bin/mpo_convert
+- lib/mpo_tools.rb
+- lib/version.rb
+- mpo_tools.gemspec
+- spec/example_data/sample.mpo
+- spec/mpo_tools_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/rawls/mpo_tools
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.19
+signing_key: 
+specification_version: 3
+summary: Tools for working with MPO format stereoscopic 3D images
+test_files:
+- spec/example_data/sample.mpo
+- spec/mpo_tools_spec.rb
+- spec/spec_helper.rb