Parsing images (#32)

* Add image parsing support

* Refactor image parsing logic and fix some issues

* Add comments to new methods for image parsing in sheet

* Add tests for parsing images

* Refactor image parsing, add comments and update tests

* Update Readme

Author: melcha

README.rdoc

@@ -51,6 +51,27 @@ Creek can parse this directly without the need for file upload gems such as Carr
       Creek::Book.new file.path, check_file_extension: false
     end
 
+== Parsing images
+Creek does not parse images by default. If you want to parse the images,
+use *with_images* method before iterating over rows to preload images information. If you don't call this method, Creek will not return images anywhere.
+
+
+Cells with images will be an array of Pathname objects.
+If an image is spread across multiple cells, same Pathname object will be returned for each cell.
+
+    sheet.with_images.rows.each do |row|
+      puts row # => {"A1"=>[#<Pathname:/var/folders/ck/l64nmm3d4k75pvxr03ndk1tm0000gn/T/creek__drawing20161101-53599-274q0vimage1.jpeg>], "B2"=>"Fluffy"}
+    end
+
+
+Images for a specific cell can be obtained with images_at method:
+     puts sheet.images_at('A1') # => [#<Pathname:/var/folders/ck/l64nmm3d4k75pvxr03ndk1tm0000gn/T/creek__drawing20161101-53599-274q0vimage1.jpeg>]
+
+     # no images in a cell
+     puts sheet.images_at('C1') # => nil
+
+Creek will most likely return nil for a cell with images if there is no other text cell in that row - you can use *images_at* method for retrieving images in that cell.
+
 == Contributing
 
 Contributions are welcomed. You can fork a repository, add your code changes to the forked branch, ensure all existing unit tests pass, create new unit tests cover your new changes and finally create a pull request.

lib/creek.rb

@@ -1,9 +1,11 @@
-require "creek/version"
+require 'creek/version'
 require 'creek/book'
 require 'creek/styles/constants'
 require 'creek/styles/style_types'
 require 'creek/styles/converter'
+require 'creek/utils'
 require 'creek/styles'
+require 'creek/drawing'
 require 'creek/sheet'
 require 'creek/shared_strings'
 

lib/creek/drawing.rb

@@ -0,0 +1,109 @@
+require 'pathname'
+
+module Creek
+  class Creek::Drawing
+    include Creek::Utils
+
+    COLUMNS = ('A'..'AZ').to_a
+
+    def initialize(book, drawing_filepath)
+      @book = book
+      @drawing_filepath = drawing_filepath
+      @drawings = []
+      @drawings_rels = []
+      @images_pathnames = Hash.new { |hash, key| hash[key] = [] }
+
+      if file_exist?(@drawing_filepath)
+        load_drawings_and_rels
+        load_images_pathnames_by_cells if has_images?
+      end
+    end
+
+    ##
+    # Returns false if there are no images in the drawing file or the drawing file does not exist, true otherwise.
+    def has_images?
+      @has_images ||= !@drawings.empty?
+    end
+
+    ##
+    # Extracts images from excel to tmpdir for a cell, if the images are not already extracted (multiple calls or same image file in multiple cells).
+    # Returns array of images as Pathname objects or nil.
+    def images_at(cell_name)
+      coordinate = calc_coordinate(cell_name)
+      pathnames_at_coordinate = @images_pathnames[coordinate]
+      return if pathnames_at_coordinate.empty?
+
+      pathnames_at_coordinate.map do |image_pathname|
+         if image_pathname.exist?
+           image_pathname
+         else
+           excel_image_path = "xl/media/#{image_pathname.to_path.split(tmpdir).last}"
+           IO.copy_stream(@book.files.file.open(excel_image_path), image_pathname.to_path)
+           image_pathname
+         end
+      end
+    end
+
+    private
+
+    ##
+    # Transforms cell name to [row, col], e.g. A1 => [0, 0], B3 => [1, 2]
+    # Rows and cols start with 0.
+    def calc_coordinate(cell_name)
+      col = COLUMNS.index(cell_name.slice /[A-Z]+/)
+      row = (cell_name.slice /\d+/).to_i - 1 # rows in drawings start with 0
+      [row, col]
+    end
+
+    ##
+    # Creates/loads temporary directory for extracting images from excel
+    def tmpdir
+      @tmpdir ||= ::Dir.mktmpdir('creek__drawing')
+    end
+
+    ##
+    # Parses drawing and drawing's relationships xmls.
+    # Drawing xml contains relationships ID's and coordinates (row, col).
+    # Drawing relationships xml contains images' locations.
+    def load_drawings_and_rels
+      @drawings = parse_xml(@drawing_filepath).css('xdr|twoCellAnchor')
+      drawing_rels_filepath = expand_to_rels_path(@drawing_filepath)
+      @drawings_rels = parse_xml(drawing_rels_filepath).css('Relationships')
+    end
+
+    ##
+    # Iterates through the drawings and saves images' paths as Pathname objects to a hash with [row, col] keys.
+    # As multiple images can be located in a single cell, hash values are array of Pathname objects.
+    # One image can be spread across multiple cells (defined with from-row/to-row/from-col/to-col attributes) - same Pathname object is associated to each row-col combination for the range.
+    def load_images_pathnames_by_cells
+      image_selector = 'xdr:pic/xdr:blipFill/a:blip'.freeze
+      row_from_selector = 'xdr:from/xdr:row'.freeze
+      row_to_selector = 'xdr:to/xdr:row'.freeze
+      col_from_selector = 'xdr:from/xdr:col'.freeze
+      col_to_selector = 'xdr:to/xdr:col'.freeze
+
+      @drawings.xpath('//xdr:twoCellAnchor').each do |drawing|
+        embed = drawing.xpath(image_selector).first.attributes['embed']
+        next if embed.nil?
+
+        rid = embed.value
+        path = Pathname.new("#{tmpdir}#{extract_drawing_path(rid).slice(/[^\/]*$/)}")
+
+        row_from = drawing.xpath(row_from_selector).text.to_i
+        col_from = drawing.xpath(col_from_selector).text.to_i
+        row_to = drawing.xpath(row_to_selector).text.to_i
+        col_to = drawing.xpath(col_to_selector).text.to_i
+
+        (col_from..col_to).each do |col|
+          (row_from..row_to).each do |row|
+            @images_pathnames[[row, col]].push(path)
+          end
+        end
+      end
+    end
+
+    def extract_drawing_path(rid)
+      @drawings_rels.css("Relationship[@Id=#{rid}]").first.attributes['Target'].value
+    end
+  end
+end

lib/creek/sheet.rb

@@ -3,6 +3,7 @@
 
 module Creek
   class Creek::Sheet
+    include Creek::Utils
 
     attr_reader :book,
                 :name,
@@ -21,6 +22,28 @@ def initialize book, name, sheetid, state, visible, rid, sheetfile
       @rid = rid
       @state = state
       @sheetfile = sheetfile
+      @images_present = false
+    end
+
+    ##
+    # Preloads images info (coordinates and paths) from related drawing.xml and drawing rels.
+    # Must be called before #rows method if you want to have images included.
+    # Returns self so you can chain the calls (sheet.with_images.rows).
+    def with_images
+      @drawingfile = extract_drawing_filepath
+      if @drawingfile
+        @drawing = Creek::Drawing.new(@book, @drawingfile.sub('..', 'xl'))
+        @images_present = @drawing.has_images?
+      end
+      self
+    end
+
+    ##
+    # Extracts images for a cell to a temporary folder.
+    # Returns array of Pathnames for the cell.
+    # Returns nil if images asre not found for the cell or images were not preloaded with #with_images.
+    def images_at(cell)
+      @drawing.images_at(cell) if @images_present
     end
 
     ##
@@ -62,6 +85,14 @@ def rows_generator include_meta_data=false
                 y << (include_meta_data ? row : cells) if node.self_closing?
               elsif (node.name.eql? 'row') and (node.node_type.eql? closer)
                 processed_cells = fill_in_empty_cells(cells, row['r'], cell)
+
+                if @images_present
+                  processed_cells.each do |cell_name, cell_value|
+                    next unless cell_value.nil?
+                    processed_cells[cell_name] = images_at(cell_name)
+                  end
+                end
+
                 row['cells'] = processed_cells
                 y << (include_meta_data ? row : processed_cells)
               elsif (node.name.eql? 'c') and (node.node_type.eql? opener)
@@ -108,5 +139,22 @@ def fill_in_empty_cells(cells, row_number, last_col)
 
       new_cells
     end
+
+    ##
+    # Find drawing filepath for the current sheet.
+    # Sheet xml contains drawing relationship ID.
+    # Sheet relationships xml contains drawing file's location.
+    def extract_drawing_filepath
+      # Read drawing relationship ID from the sheet.
+      sheet_filepath = "xl/#{@sheetfile}"
+      drawing = parse_xml(sheet_filepath).css('drawing').first
+      return if drawing.nil?
+
+      drawing_rid = drawing.attributes['id'].value
+
+      # Read sheet rels to find drawing file's location.
+      sheet_rels_filepath = expand_to_rels_path(sheet_filepath)
+      parse_xml(sheet_rels_filepath).css("Relationship[@Id='#{drawing_rid}']").first.attributes['Target'].value
+    end
   end
-end
+end

lib/creek/utils.rb

@@ -0,0 +1,16 @@
+module Creek
+  module Utils
+    def expand_to_rels_path(filepath)
+      filepath.sub(/(\/[^\/]+$)/, '/_rels\1.rels')
+    end
+
+    def file_exist?(path)
+      @book.files.file.exist?(path)
+    end
+
+    def parse_xml(xml_path)
+      doc = @book.files.file.open(xml_path)
+      Nokogiri::XML::Document.parse(doc)
+    end
+  end
+end

spec/drawing_spec.rb

@@ -0,0 +1,52 @@
+require './spec/spec_helper'
+
+describe 'drawing' do
+  let(:book) { Creek::Book.new('spec/fixtures/sample-with-images.xlsx') }
+  let(:book_no_images) { Creek::Book.new('spec/fixtures/sample.xlsx') }
+  let(:drawingfile) { 'xl/drawings/drawing1.xml' }
+  let(:drawing) { Creek::Drawing.new(book, drawingfile) }
+  let(:drawing_without_images) { Creek::Drawing.new(book_no_images, drawingfile) }
+
+  describe '#has_images?' do
+    it 'has' do
+      expect(drawing.has_images?).to eq(true)
+    end
+
+    it 'does not have' do
+      expect(drawing_without_images.has_images?).to eq(false)
+    end
+  end
+
+  describe '#images_at' do
+    it 'returns images pathnames at cell' do
+      image = drawing.images_at('A2')[0]
+      expect(image.class).to eq(Pathname)
+      expect(image.exist?).to eq(true)
+      expect(image.to_path).to match(/.+creek__drawing.+\.jpeg$/)
+    end
+
+    context 'when no images in cell' do
+      it 'returns nil' do
+        images = drawing.images_at('B2')
+        expect(images).to eq(nil)
+      end
+    end
+
+    context 'when more images in one cell' do
+      it 'returns all images at cell' do
+        images = drawing.images_at('A10')
+        expect(images.size).to eq(2)
+        expect(images.all?(&:exist?)).to eq(true)
+      end
+    end
+
+    context 'when same image across multiple cells' do
+      it 'returns same image for each cell' do
+        image1 = drawing.images_at('A4')[0]
+        image2 = drawing.images_at('A5')[0]
+        expect(image1.class).to eq(Pathname)
+        expect(image1).to eq(image2)
+      end
+    end
+  end
+end

spec/fixtures/sample-with-images.xlsx

@@ -0,0 +1,85 @@
+require './spec/spec_helper'
+
+describe 'sheet' do
+  let(:book_with_images) { Creek::Book.new('spec/fixtures/sample-with-images.xlsx') }
+  let(:book_no_images) { Creek::Book.new('spec/fixtures/sample.xlsx') }
+  let(:sheetfile) { 'worksheets/sheet1.xml' }
+  let(:sheet_with_images) { Creek::Sheet.new(book_with_images, 'Sheet 1', 1, '', '', '1', sheetfile) }
+  let(:sheet_no_images) { Creek::Sheet.new(book_no_images, 'Sheet 1', 1, '', '', '1', sheetfile) }
+
+  def load_cell(rows, cell_name)
+    cell = rows.find { |row| !row[cell_name].nil? }
+    cell[cell_name] if cell
+  end
+
+  describe '#rows' do
+    context 'with excel with images' do
+      context 'with images preloading' do
+        let(:rows) { sheet_with_images.with_images.rows.map { |r| r } }
+
+        it 'parses single image in a cell' do
+          expect(load_cell(rows, 'A2').size).to eq(1)
+        end
+
+        it 'returns nil for cells without images' do
+          expect(load_cell(rows, 'A3')).to eq(nil)
+          expect(load_cell(rows, 'A7')).to eq(nil)
+          expect(load_cell(rows, 'A9')).to eq(nil)
+        end
+
+        it 'returns nil for merged cell within empty row' do
+          expect(load_cell(rows, 'A5')).to eq(nil)
+        end
+
+        it 'returns nil for image in a cell with empty row' do
+          expect(load_cell(rows, 'A8')).to eq(nil)
+        end
+
+        it 'returns images for merged cells' do
+          expect(load_cell(rows, 'A4').size).to eq(1)
+          expect(load_cell(rows, 'A6').size).to eq(1)
+        end
+
+        it 'returns multiple images' do
+          expect(load_cell(rows, 'A10').size).to eq(2)
+        end
+      end
+
+      it 'ignores images' do
+        rows = sheet_with_images.rows.map { |r| r }
+        expect(load_cell(rows, 'A2')).to eq(nil)
+        expect(load_cell(rows, 'A3')).to eq(nil)
+        expect(load_cell(rows, 'A4')).to eq(nil)
+      end
+    end
+
+    context 'with excel without images' do
+      it 'does not break on with_images' do
+        rows = sheet_no_images.with_images.rows.map { |r| r }
+        expect(load_cell(rows, 'A10')).to eq(nil)
+      end
+    end
+  end
+
+  describe '#images_at' do
+    it 'returns images for merged cell' do
+      image = sheet_with_images.with_images.images_at('A5')[0]
+      expect(image.class).to eq(Pathname)
+    end
+
+    it 'returns images for empty row' do
+      image = sheet_with_images.with_images.images_at('A8')[0]
+      expect(image.class).to eq(Pathname)
+    end
+
+    it 'returns nil for empty cell' do
+      image = sheet_with_images.with_images.images_at('B3')
+      expect(image).to eq(nil)
+    end
+
+    it 'returns nil for empty cell without preloading images' do
+      image = sheet_with_images.images_at('B3')
+      expect(image).to eq(nil)
+    end
+  end
+end