newspaper_works 0.1.0 → 1.0.0

data/config/vendor/fits.xml

@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<fits_configuration>
+	<!-- Order of the tools determines preference -->
+	<tools>
+		<!-- exclude-exts attribute is a comma delimited list of file extensions that the tool should not try to process -->
+        <!-- include-exts attribute is a comma delimited list of file extensions that are the only ones the tool will process -->
+        <!-- classpath-dirs attribute is a list of directories where any tool-specific Java JAR files and configuration files used solely by these JAR files -->
+        <tool class="edu.harvard.hul.ois.fits.tools.mediainfo.MediaInfo" include-exts="avi,mov,mpg,mpeg,mkv,mp4,mxf,ogv,mj2,divx,dv,m4v,m2v,ismv,m2ts,mpeg4" classpath-dirs="lib/mediainfo" />
+        <tool class="edu.harvard.hul.ois.fits.tools.oisfileinfo.AudioInfo" include-exts="wav" classpath-dirs="lib/audioinfo" />
+        <tool class="edu.harvard.hul.ois.fits.tools.oisfileinfo.ADLTool" include-exts="adl" classpath-dirs="lib/adltool" />
+        <tool class="edu.harvard.hul.ois.fits.tools.oisfileinfo.VTTTool" include-exts="vtt" />
+        <tool class="edu.harvard.hul.ois.fits.tools.droid.Droid"  exclude-exts="odm,m4a" classpath-dirs="lib/droid" />
+        <tool class="edu.harvard.hul.ois.fits.tools.jhove.Jhove" exclude-exts="dng,mbx,mbox,arw,adl,eml,java,doc,docx,docm,odt,rtf,pages,wpd,wp,epub,csv,avi,mov,mpg,mpeg,mkv,mp4,mpeg4,m2ts,mxf,ogv,mj2,divx,dv,m4v,m2v,ismv,pcd,zip" classpath-dirs="lib/jhove" />
+        <tool class="edu.harvard.hul.ois.fits.tools.fileutility.FileUtility" exclude-exts="dng,wps,adl,jar,epub,csv" classpath-dirs="lib/fileutility" />
+        <tool class="edu.harvard.hul.ois.fits.tools.exiftool.Exiftool" exclude-exts="txt,wps,vsd,jar,avi,mov,mpg,mpeg,mkv,mp4,mxf,ogv,mj2,divx,dv,m4v,m2v,ismv,m2ts,mpeg4" classpath-dirs="lib/exiftool" />
+        <tool class="edu.harvard.hul.ois.fits.tools.nlnz.MetadataExtractor" include-exts="bmp,gif,jpg,jpeg,wp,wpd,odt,doc,pdf,mp3,bfw,flac,html,xml,arc" classpath-dirs="lib/nzmetool,xml/nlnz"/>
+        <tool class="edu.harvard.hul.ois.fits.tools.oisfileinfo.FileInfo" classpath-dirs="lib/fileinfo" />
+        <tool class="edu.harvard.hul.ois.fits.tools.oisfileinfo.XmlMetadata" include-exts="xml" classpath-dirs="lib/xmlmetadata" />
+        <tool class="edu.harvard.hul.ois.fits.tools.ffident.FFIdent" exclude-exts="dng,wps,vsd,jar,ppt,rtf" classpath-dirs="lib/ffident" />
+
+	</tools>
+	
+	<output>
+		<dataConsolidator class="edu.harvard.hul.ois.fits.consolidation.OISConsolidator"/>
+		<display-tool-output>false</display-tool-output>
+		<report-conflicts>true</report-conflicts>	
+		<validate-tool-output>false</validate-tool-output>
+		<internal-output-schema>xml/fits_output.xsd</internal-output-schema>
+		<external-output-schema>http://hul.harvard.edu/ois/xml/xsd/fits/fits_output.xsd</external-output-schema>
+		<fits-xml-namespace>http://hul.harvard.edu/ois/xml/ns/fits/fits_output</fits-xml-namespace>
+		<enable-statistics>true</enable-statistics>
+		<enable-checksum>true</enable-checksum>
+		<!-- The below controls the exclusion of the checksum for certain files, even if enable-checksum is true -->
+		<!-- Video Exclusions -->
+		<!-- <checksum-exclusions exclude-exts="avi,mov,mpg,mkv,mp4,mxf,ogv,mj2,divx,dv,m4v,m2v,ismv"/> -->
+		<!-- Audio Exclusions -->
+		<!-- <checksum-exclusions exclude-exts="wav,aif,mp3,mp4,m4a,ra,rm"/> -->
+	</output>
+	
+	<process>
+		<max-threads>20</max-threads>
+	</process>
+	
+	<!-- file name of the droid signature file to use in tools/droid/-->
+	<droid_sigfile>DROID_SignatureFile_V90.xml</droid_sigfile>
+	<!-- Limits number of bytes DROID reads in (in KB) for processing large files for the listed file extensions. -->
+	<!-- Note: This should only be used with files that can provide sufficient metadata at beginning of the file -->
+	<!-- <droid_read_limit include-exts="mov,mxf" read-limit-kb="64" /> -->
+	
+	<!-- the fits home is used by the MediaInfo tool to load the jna api libs  -->
+	<!-- in most cases you won't need to change -->
+	<!-- example for BB will be /fits -->
+	<fits_home>.</fits_home>	
+		
+</fits_configuration>

data/config/vendor/imagemagick-6-policy.xml

@@ -2,61 +2,60 @@
 <!DOCTYPE policymap [
 <!ELEMENT policymap (policy)+>
 <!ELEMENT policy (#PCDATA)>
-<!ATTLIST policy domain (delegate|coder|filter|path|resource) #IMPLIED>
+<!ATTLIST policy domain (delegate|coder|filter|path|resource|cache) #IMPLIED>
 <!ATTLIST policy name CDATA #IMPLIED>
 <!ATTLIST policy rights CDATA #IMPLIED>
 <!ATTLIST policy pattern CDATA #IMPLIED>
 <!ATTLIST policy value CDATA #IMPLIED>
 ]>
-<policy domain="coder" rights="read|write" pattern="PDF" />
-<policy domain="coder" rights="read|write" pattern="LABEL" />
-<!--
-  Configure ImageMagick policies.
+<policymap>
+  <policy domain="coder" rights="read|write" pattern="PDF" />
+  <policy domain="coder" rights="read|write" pattern="LABEL" />
+  <!--
+    Configure ImageMagick policies.
 
-  Domains include system, delegate, coder, filter, path, or resource.
+    Domains include system, delegate, coder, filter, path, or resource.
 
-  Rights include none, read, write, and execute.  Use | to combine them,
-  for example: "read | write" to permit read from, or write to, a path.
+    Rights include none, read, write, and execute.  Use | to combine them,
+    for example: "read | write" to permit read from, or write to, a path.
 
-  Use a glob expression as a pattern.
+    Use a glob expression as a pattern.
 
-  Suppose we do not want users to process MPEG video images:
+    Suppose we do not want users to process MPEG video images:
 
-    <policy domain="delegate" rights="none" pattern="mpeg:decode" />
+      <policy domain="delegate" rights="none" pattern="mpeg:decode" />
 
-  Here we do not want users reading images from HTTP:
+    Here we do not want users reading images from HTTP:
 
-    <policy domain="coder" rights="none" pattern="HTTP" />
+      <policy domain="coder" rights="none" pattern="HTTP" />
 
-  Lets prevent users from executing any image filters:
+    Lets prevent users from executing any image filters:
 
-    <policy domain="filter" rights="none" pattern="*" />
+      <policy domain="filter" rights="none" pattern="*" />
 
-  The /repository file system is restricted to read only.  We use a glob
-  expression to match all paths that start with /repository:
-  
-    <policy domain="path" rights="read" pattern="/repository/*" />
+    The /repository file system is restricted to read only.  We use a glob
+    expression to match all paths that start with /repository:
+    
+      <policy domain="path" rights="read" pattern="/repository/*" />
 
-  Any large image is cached to disk rather than memory:
+    Any large image is cached to disk rather than memory:
 
-    <policy domain="resource" name="area" value="1GB"/>
+      <policy domain="resource" name="area" value="1GB"/>
+
+    Define arguments for the memory, map, area, and disk resources with
+    SI prefixes (.e.g 100MB).  In addition, resource policies are maximums for
+    each instance of ImageMagick (e.g. policy memory limit 1GB, -limit 2GB
+    exceeds policy maximum so memory limit is 1GB).
+  -->
+
+  <!-- NewspaperWorks: allow more than default Ubuntu policy, re: RAM, Disk -->
+  <policy domain="resource" name="memory" value="512MiB"/>
+  <policy domain="resource" name="map" value="1GiB"/>
+  <policy domain="resource" name="width" value="20KP"/>
+  <policy domain="resource" name="height" value="20KP"/>
+  <policy domain="resource" name="area" value="128MB"/>
+  <policy domain="resource" name="disk" value="2GiB"/>
 
-  Define arguments for the memory, map, area, and disk resources with
-  SI prefixes (.e.g 100MB).  In addition, resource policies are maximums for
-  each instance of ImageMagick (e.g. policy memory limit 1GB, -limit 2GB
-  exceeds policy maximum so memory limit is 1GB).
--->
-<policymap>
-  <!-- <policy domain="resource" name="temporary-path" value="/tmp"/> -->
-  <!-- <policy domain="resource" name="memory" value="2GiB"/> -->
-  <!-- <policy domain="resource" name="map" value="4GiB"/> -->
-  <!-- <policy domain="resource" name="area" value="1GB"/> -->
-  <!-- <policy domain="resource" name="disk" value="16EB"/> -->
-  <!-- <policy domain="resource" name="file" value="768"/> -->
-  <!-- <policy domain="resource" name="thread" value="4"/> -->
-  <!-- <policy domain="resource" name="throttle" value="0"/> -->
-  <!-- <policy domain="resource" name="time" value="3600"/> -->
-  <!-- <policy domain="system" name="precision" value="6"/> -->
   <policy domain="cache" name="shared-secret" value="passphrase"/>
   <policy domain="coder" rights="none" pattern="EPHEMERAL" />
   <policy domain="coder" rights="none" pattern="URL" />
@@ -68,9 +67,10 @@
   <policy domain="coder" rights="none" pattern="WIN" />
   <policy domain="coder" rights="none" pattern="PLT" />
   <policy domain="path" rights="none" pattern="@*" />
-  <!-- disable ghostscript format types -->
+  <!-- disable ghostscript format types (except PDF) -->
   <policy domain="coder" rights="none" pattern="PS" />
   <policy domain="coder" rights="none" pattern="EPS" />
-  <!-- <policy domain="coder" rights="none" pattern="PDF" /> -->
   <policy domain="coder" rights="none" pattern="XPS" />
+  <!-- NewspaperWorks: we need to allow PDF here -->
+  <!-- <policy domain="coder" rights="none" pattern="PDF" /> -->
 </policymap>

data/lib/newspaper_works.rb

@@ -1,5 +1,7 @@
 require "newspaper_works/engine"
 require "newspaper_works/errors"
+require "newspaper_works/jp2_image_metadata"
+require "newspaper_works/image_tool"
 require "newspaper_works/ingest"
 require "newspaper_works/issue_pdf_composer"
 require "newspaper_works/text_extraction"

data/lib/newspaper_works/image_tool.rb

@@ -0,0 +1,119 @@
+require 'open3'
+require 'tmpdir'
+
+module NewspaperWorks
+  class ImageTool
+    attr_accessor :path, :ftype
+
+    def initialize(path)
+      @path = path
+      @ftype = magic
+      @metadata = nil
+    end
+
+    # @return [Hash] hash with following symbol keys, and respectively
+    #   typed String and/or Integer values.
+    #   :width, :height — both in Integer px units
+    #   :color — (String enumerated from 'gray', 'monochrome', 'color')
+    #   :num_components - Integer, number of channels
+    #   :bits_per_component — Integer, bits per channel (e.g. 8 vs. 1)
+    #   :content_type — RFC 2045 MIME type
+    def metadata
+      return @metadata unless @metadata.nil?
+      @metadata = jp2? ? jp2_metadata : identify_metadata
+    end
+
+    # Convert source image to image at destination path, inferring file type
+    #   from destination file extension.  In case of JP2 files, create
+    #   intermediate file using OpenJPEG 2000 that ImageMagick can use.
+    #   Only outputs monochrome output if monochrome is true, destination
+    #   format is TIFF.
+    # @param destination [String] Path to output / destination file
+    # @param monochrome [Boolean] true if monochrome output, otherwise false
+    def convert(destination, monochrome = false)
+      raise 'JP2 output not yet supported' if destination.end_with?('jp2')
+      return convert_image(jp2_to_tiff(@path), destination, monochrome) if jp2?
+      convert_image(@path, destination, monochrome)
+    end
+
+    private
+
+      def convert_image(source, destination, monochrome)
+        monochrome &&= destination.slice(-4, 4).index('tif')
+        mono_opts = "-depth 1 -monochrome -compress Group4 -type bilevel "
+        opts = monochrome ? mono_opts : ''
+        cmd = "convert #{source} #{opts}#{destination}"
+        `#{cmd}`
+      end
+
+      def jp2_to_tiff(source)
+        intermediate_path = File.join(Dir.mktmpdir, 'intermediate.tif')
+        jp2_cmd = "opj_decompress -i #{source} -o #{intermediate_path}"
+        `#{jp2_cmd}`
+        intermediate_path
+      end
+
+      def jp2_metadata
+        result = NewspaperWorks::JP2ImageMetadata.new(path).technical_metadata
+        result[:content_type] = 'image/jp2'
+        result
+      end
+
+      def im_line_select(lines, key)
+        line = lines.select { |l| l.downcase.strip.start_with?(key) }[0]
+        # Given "key: value" line, return the value as String stripped of
+        #   leading and trailing whitespace
+        return line if line.nil?
+        line.strip.split(':')[-1].strip
+      end
+
+      # @return [Array(Integer, Integer)] width, height in Integer px units
+      def im_identify_geometry(lines)
+        img_geo = im_line_select(lines, 'geometry').split('+')[0]
+        img_geo.split('x').map(&:to_i)
+      end
+
+      # @return [Array<String>] lines of output from imagemagick `identify`
+      def im_identify
+        cmd = "identify -verbose #{path}"
+        `#{cmd}`.lines
+      end
+
+      def im_mime(lines)
+        return 'application/pdf' if pdf? # workaround older imagemagick bug
+        im_line_select(lines, 'mime type')
+      end
+
+      def populate_im_color!(lines, result)
+        bpc = im_line_select(lines, 'depth').split('-')[0].to_i # '1-bit' -> 1
+        colorspace = im_line_select(lines, 'colorspace')
+        color = colorspace == 'Gray' ? 'gray' : 'color'
+        has_alpha = !im_line_select(lines, 'Alpha').nil?
+        result[:num_components] = (color == 'gray' ? 1 : 3) + (has_alpha ? 1 : 0)
+        result[:color] = bpc == 1 ? 'monochrome' : color
+        result[:bits_per_component] = bpc
+      end
+
+      # Return metadata by means of imagemagick identify
+      def identify_metadata
+        result = {}
+        lines = im_identify
+        result[:width], result[:height] = im_identify_geometry(lines)
+        result[:content_type] = im_mime(lines)
+        populate_im_color!(lines, result)
+        result
+      end
+
+      def magic
+        File.read(@path, 23, 0)
+      end
+
+      def jp2?
+        @ftype.end_with?('ftypjp2')
+      end
+
+      def pdf?
+        magic.start_with?('%PDF-')
+      end
+  end
+end

data/lib/newspaper_works/jp2_image_metadata.rb

@@ -0,0 +1,81 @@
+module NewspaperWorks
+  class JP2ImageMetadata
+    TOKEN_MARKER_START = "\xFF".force_encoding("BINARY").freeze
+    TOKEN_MARKER_SIZ = "\x51".force_encoding("BINARY").freeze
+    TOKEN_IHDR = 'ihdr'.freeze
+
+    attr_accessor :path
+
+    def initialize(path)
+      @path = path
+    end
+
+    # @param io [IO] IO stream opened in binary mode, for reading
+    # @return [Array(Integer, Integer)] X size, Y size, in Integer-typed px
+    def extract_jp2_dim(io)
+      raise IOError, 'file not open in binary mode' unless io.binmode?
+      buffer = ''
+      siz_found = false
+      # Informed by ISO/IEC 15444-1:2000, pp. 26-27
+      #   via:
+      #   http://hosting.astro.cornell.edu/~carcich/LRO/jp2/ISO_JPEG200_Standard/INCITS+ISO+IEC+15444-1-2000.pdf
+      #
+      # first 23 bytes are file-magic, we can skip
+      io.seek(23, IO::SEEK_SET)
+      while !siz_found && !buffer.nil?
+        # read one byte at a time, until we hit marker start 0xFF
+        buffer = io.read(1) while buffer != TOKEN_MARKER_START
+        # - on 0xFF read subsequent byte; if value != 0x51, continue
+        buffer = io.read(1)
+        next if buffer != TOKEN_MARKER_SIZ
+        # - on 0x51, read next 12 bytes
+        buffer = io.read(12)
+        siz_found = true
+      end
+      # discard first 4 bytes; next 4 bytes are XSiz; last 4 bytes are YSiz
+      x_siz = buffer.byteslice(4, 4).unpack('N').first
+      y_siz = buffer.byteslice(8, 4).unpack('N').first
+      [x_siz, y_siz]
+    end
+
+    # @param io [IO] IO stream opened in binary mode, for reading
+    # @return [Array(Integer, Integer)] number components, bits-per-component
+    def extract_jp2_components(io)
+      raise IOError, 'file not open in binary mode' unless io.binmode?
+      io.seek(0, IO::SEEK_SET)
+      # IHDR should be in first 64 bytes
+      buffer = io.read(64)
+      ihdr_data = buffer.split(TOKEN_IHDR)[-1]
+      raise IOError if ihdr_data.nil?
+      num_components = ihdr_data.byteslice(8, 2).unpack('n').first
+      # stored as "bit depth of the components in the codestream, minus 1", so add 1
+      bits_per_component = ihdr_data.byteslice(10, 1).unpack('c').first + 1
+      [num_components, bits_per_component]
+    end
+
+    def validate_jp2(io)
+      # verify file is jp2
+      magic = io.read(23)
+      raise IOError, 'Not JP2 file' unless magic.end_with?('ftypjp2')
+    end
+
+    # @param path [String] path to jp2, for reading
+    # @return [Hash] hash
+    def technical_metadata
+      io = File.open(path, 'rb')
+      io.seek(0, IO::SEEK_SET)
+      validate_jp2(io)
+      x_siz, y_siz = extract_jp2_dim(io)
+      nc, bpc = extract_jp2_components(io)
+      color = nc >= 3 ? 'color' : 'gray'
+      io.close
+      {
+        color: bpc == 1 ? 'monochrome' : color,
+        num_components: nc,
+        bits_per_component: bpc,
+        width: x_siz,
+        height: y_siz
+      }
+    end
+  end
+end

data/lib/newspaper_works/text_extraction.rb

@@ -1,4 +1,5 @@
 require 'newspaper_works/text_extraction/alto_reader'
+require 'newspaper_works/text_extraction/hocr_reader'
 require 'newspaper_works/text_extraction/page_ocr'
 require 'newspaper_works/text_extraction/render_alto'
 require 'newspaper_works/text_extraction/word_coords_builder'

data/lib/newspaper_works/text_extraction/hocr_reader.rb

@@ -0,0 +1,173 @@
+require 'active_support/core_ext/module/delegation'
+require 'json'
+require 'nokogiri'
+
+module NewspaperWorks
+  # Module for text extraction
+  module TextExtraction
+    # Class to obtain plain text and JSON word-coordinates from hOCR source
+    #   - Coordinates in px units, unlike ALTO, which may have scaling concerns
+    class HOCRReader
+      attr_accessor :source, :doc_stream
+      delegate :text, :width, :height, :words, to: :doc_stream
+
+      # SAX Document Stream class to gather text and word tokens from hOCR
+      class HOCRDocStream < Nokogiri::XML::SAX::Document
+        attr_accessor :text, :words, :width, :height
+
+        def initialize
+          super()
+          # plain text buffer:
+          @text = ''
+          # list of word hash, containing word+coord:
+          @words = []
+          # page width and height to be found in hOCR for `div.ocr_page`
+          @width = nil
+          @height = nil
+          # to hold current word data state across #start_element, #characters,
+          #   and #end_element methods (to associate word with coordinates).
+          @current = nil
+          # to preserve element classname from start to use by #end_element
+          @element_class_name = nil
+        end
+
+        # Return coordinates from `span.ocrx_word` element attribute hash
+        #
+        # @param attrs [Hash] hash with hOCR `span.ocrx_word` element attributes
+        # @return [Array] Array of position x, y, width, height in px.
+        def s_coords(attrs)
+          element_title = attrs['title']
+          bbox = element_title.split(';')[0].split('bbox ')[-1]
+          x1, y1, x2, y2 = bbox.split(' ').map(&:to_i)
+          height = y2 - y1
+          width = x2 - x1
+          hpos = x1
+          vpos = y1
+          [hpos, vpos, width, height]
+        end
+
+        # Consider element for processing?
+        #   - `div.ocr_page` — to get page width/height
+        #   - `span.ocr_line` — to help make plain text readable
+        #   - `span.ocrx_word` — for word-coordinate JSON and plain text word
+        # @param name [String] Element name
+        # @param class_name [String] HTML class name
+        # @return [Boolean] true if element should be processed; otherwise false
+        def consider?(name, class_name)
+          selector = "#{name}.#{class_name}"
+          ['div.ocr_page', 'span.ocr_line', 'span.ocrx_word'].include?(selector)
+        end
+
+        def start_word(attrs)
+          @current = {}
+          # will be replaced during #characters method call:
+          @current[:word] = nil
+          @current[:coordinates] = s_coords(attrs)
+        end
+
+        def start_page(attrs)
+          title = attrs['title']
+          fields = title.split(';')
+          bbox = fields[1].split('bbox ')[-1].split(' ').map(&:to_i)
+          # width and height:
+          @width = bbox[2]
+          @height = bbox[3]
+        end
+
+        def word_complete?
+          return false if @current.nil?
+          coords = @current[:coordinates]
+          @current[:word] && !@current[:word].empty? && coords.size == 4
+        end
+
+        def end_word
+          # add trailing space to plaintext buffer for between words:
+          @text += ' '
+          @words.push(@current) if word_complete?
+        end
+
+        def end_line
+          # strip trailing whitespace
+          @text.strip!
+          # then insert a line break
+          @text += "\n"
+        end
+
+        # Callback for element start, ignores elements except for:
+        #   - `div.ocr_page` — to get page width/height
+        #   - `span.ocr_line` — to help make plain text readable
+        #   - `span.ocrx_word` — for word-coordinate JSON and plain text word
+        #
+        # @param name [String] element name.
+        # @param attrs [Array] Array of key, value pair Arrays.
+        def start_element(name, attrs = [])
+          attributes = attrs.to_h
+          @element_class_name = attributes['class']
+          return unless consider?(name, @element_class_name)
+          start_word(attributes) if @element_class_name == 'ocrx_word'
+          start_page(attributes) if @element_class_name == 'ocr_page'
+        end
+
+        def characters(value)
+          return if @current.nil?
+          return if @current[:coordinates].nil?
+          @current[:word] ||= ''
+          @current[:word] += value
+          @text += value
+        end
+
+        # Callback for element end; at this time, flush word coordinate state
+        #   for current word, and append line endings to plain text:
+        #
+        # @param name [String] element name.
+        def end_element(_name)
+          end_line if @element_class_name == 'ocr_line'
+          end_word if @element_class_name == 'ocrx_word'
+        end
+
+        # Callback for completion of parsing hOCR, used to normalize generated
+        #   text content (strip unneeded whitespace incidental to output).
+        def end_document
+          # postprocess @text to remove trailing spaces on lines
+          @text = @text.split("\n").map(&:strip).join("\n")
+          # remove excess line break
+          @text.gsub!(/\n+/, "\n")
+          @text.delete("\r")
+          # remove trailing whitespace at end of buffer
+          @text.strip!
+        end
+      end
+
+      # Construct with either path or HTML [String]
+      #
+      # @param html [String], and process document
+      def initialize(html)
+        @source = isxml?(html) ? html : File.read(html)
+        @doc_stream = HOCRDocStream.new
+        parser = Nokogiri::HTML::SAX::Parser.new(doc_stream)
+        parser.parse(@source)
+      end
+
+      # Determine if source parameter is path or xml/html
+      #
+      # @param xml [String] either path to xml file or xml source
+      # @return [true, false] true if value appears to be XML/HTML, not path
+      def isxml?(xml)
+        xml.lstrip.start_with?('<')
+      end
+
+      # Output JSON flattened word coordinates
+      #
+      # @return [String] JSON serialization of flattened word coordinates
+      def json
+        words = @doc_stream.words
+        builder = NewspaperWorks::TextExtraction::WordCoordsBuilder.new(
+          words,
+          @doc_stream.width,
+          @doc_stream.height
+        )
+        builder.to_json
+      end
+    end
+  end
+end