Class: Uniword::Image

Inherits:
Element
  • Object
show all
Extended by:
LazyLoader
Defined in:
lib/uniword/image.rb

Overview

Represents an image (inline element) Responsibility: Hold image reference and metadata

An image is an inline element that references an external image file. It contains metadata about the image such as dimensions and relationship ID.

Uses lazy loading to defer loading of actual image data until needed, which improves memory efficiency for documents with many images.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from LazyLoader

lazy_attr, lazy_collection

Methods inherited from Element

abstract!, abstract?, #valid?

Instance Attribute Details

#cached_data ⇒ Object (readonly)

Cached image data (lazy loaded)



60
61
62
 
# File 'lib/uniword/image.rb', line 60

def cached_data
  @cached_data
end

#data_loader ⇒ Object

Image data loader (proc that loads the actual binary data) This is not serialized - it’s used for lazy loading



57
58
59
 
# File 'lib/uniword/image.rb', line 57

def data_loader
  @data_loader
end

Class Method Details

.from_base64(base64_data, width: nil, height: nil, alt_text: nil, title: nil) ⇒ Image

Create image from base64 encoded data

Parameters:

  • base64_data (String) —

    Base64 encoded image data

  • width (Integer, nil) (defaults to: nil) —

    Width in EMUs

  • height (Integer, nil) (defaults to: nil) —

    Height in EMUs

  • alt_text (String, nil) (defaults to: nil) —

    Alternative text

  • title (String, nil) (defaults to: nil) —

    Image title

Returns:

  • (Image) —

    New image instance



197
198
199
200
201
202
 
# File 'lib/uniword/image.rb', line 197

def self.from_base64(base64_data, width: nil, height: nil, alt_text: nil,
title: nil)
  binary_data = Base64.decode64(base64_data)
  from_data(binary_data, width: width, height: height, alt_text: alt_text,
                         title: title)
end

.from_data(binary_data, width: nil, height: nil, alt_text: nil, title: nil) ⇒ Image

Create image from binary data

Parameters:

  • binary_data (String) —

    Binary image data

  • width (Integer, nil) (defaults to: nil) —

    Width in EMUs

  • height (Integer, nil) (defaults to: nil) —

    Height in EMUs

  • alt_text (String, nil) (defaults to: nil) —

    Alternative text

  • title (String, nil) (defaults to: nil) —

    Image title

Returns:

  • (Image) —

    New image instance



212
213
214
215
216
217
218
219
220
221
222
223
 
# File 'lib/uniword/image.rb', line 212

def self.from_data(binary_data, width: nil, height: nil, alt_text: nil,
title: nil)
  image = new(
    width: width,
    height: height,
    alt_text: alt_text,
    title: title,
    relationship_id: "temp_#{SecureRandom.hex(8)}",
  )
  image.image_data = binary_data
  image
end

Instance Method Details

#accept(visitor) ⇒ Object

Accept a visitor for the visitor pattern

Parameters:

  • visitor (Object) —

    The visitor object

Returns:

  • (Object) —

    The result of the visit operation



120
121
122
 
# File 'lib/uniword/image.rb', line 120

def accept(visitor)
  visitor.visit_image(self)
end

#aspect_ratio ⇒ Float?

Get aspect ratio

Returns:

  • (Float, nil) —

    Aspect ratio (width/height)



183
184
185
186
187
 
# File 'lib/uniword/image.rb', line 183

def aspect_ratio
  return nil unless width && height&.positive?

  width.to_f / height
end

#clear_image_data ⇒ void

This method returns an undefined value.

Clear cached image data to free memory



81
82
83
 
# File 'lib/uniword/image.rb', line 81

def clear_image_data
  remove_instance_variable(:@cached_data) if defined?(@cached_data)
end

#floating ⇒ Boolean

Check if image is floating (not inline)

Returns:

  • (Boolean) —

    true if floating



112
113
114
 
# File 'lib/uniword/image.rb', line 112

def floating
  !inline
end

#floating=(value) ⇒ Boolean

Set floating mode (not inline)

Returns:

  • (Boolean) —

    true



105
106
107
 
# File 'lib/uniword/image.rb', line 105

def floating=(value)
  self.inline = !value
end

#height_in_pixels ⇒ Integer?

Get height in pixels (assuming 96 DPI) 1 pixel = 9525 EMUs at 96 DPI

Returns:

  • (Integer, nil) —

    Height in pixels



174
175
176
177
178
 
# File 'lib/uniword/image.rb', line 174

def height_in_pixels
  return nil unless height

  (height / 9525.0).round
end

#height_in_points ⇒ Float?

Get height in points (converted from EMUs) 1 point = 12700 EMUs

Returns:

  • (Float, nil) —

    Height in points



154
155
156
157
158
 
# File 'lib/uniword/image.rb', line 154

def height_in_points
  return nil unless height

  height / 12_700.0
end

#image_data ⇒ String?

Load image data lazily

Returns:

  • (String, nil) —

    The binary image data



65
66
67
68
69
 
# File 'lib/uniword/image.rb', line 65

def image_data
  return @image_data if defined?(@image_data)

  @image_data = @data_loader&.call
end

#image_data=(data) ⇒ String

Set image data (for manual assignment)

Parameters:

  • data (String) —

    The binary image data

Returns:

  • (String) —

    The data



89
90
91
 
# File 'lib/uniword/image.rb', line 89

def image_data=(data)
  @cached_data = data
end

#image_data_loaded? ⇒ Boolean

Check if image data is loaded

Returns:

  • (Boolean) —

    true if image data is cached



74
75
76
 
# File 'lib/uniword/image.rb', line 74

def image_data_loaded?
  defined?(@cached_data)
end

#image_size ⇒ Integer?

Get image size without loading full data

Returns:

  • (Integer, nil) —

    The size in bytes if data is loaded



96
97
98
99
100
 
# File 'lib/uniword/image.rb', line 96

def image_size
  return nil unless image_data_loaded?

  @cached_data&.bytesize
end

#properties ⇒ nil

Get properties (images don’t have RunProperties) Compatible with Run API for serialization

Returns:

  • (nil) —

    Always returns nil (images don’t have RunProperties)



136
137
138
 
# File 'lib/uniword/image.rb', line 136

def properties
  nil
end

#save(path) ⇒ Integer

Save image data to a file Convenient method to save image data to disk

Parameters:

  • path (String) —

    The file path to save to

Returns:

  • (Integer) —

    Number of bytes written

Raises:

  • (RuntimeError) —

    if no image data is available



231
232
233
234
235
236
 
# File 'lib/uniword/image.rb', line 231

def save(path)
  data_to_save = image_data
  raise "No image data available to save" unless data_to_save

  File.binwrite(path, data_to_save)
end

#text ⇒ String

Get text content (images have no text) Compatible with Run API for text extraction

Returns:

  • (String) —

    Empty string (images don’t have text)



128
129
130
 
# File 'lib/uniword/image.rb', line 128

def text
  ""
end

#width_in_pixels ⇒ Integer?

Get width in pixels (assuming 96 DPI) 1 pixel = 9525 EMUs at 96 DPI

Returns:

  • (Integer, nil) —

    Width in pixels



164
165
166
167
168
 
# File 'lib/uniword/image.rb', line 164

def width_in_pixels
  return nil unless width

  (width / 9525.0).round
end

#width_in_points ⇒ Float?

Get width in points (converted from EMUs) 1 point = 12700 EMUs

Returns:

  • (Float, nil) —

    Width in points



144
145
146
147
148
 
# File 'lib/uniword/image.rb', line 144

def width_in_points
  return nil unless width

  width / 12_700.0
end