gubbins-shell 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. checksums.yaml +7 -0
  2. data/CHANGELOG.md +19 -0
  3. data/LICENSE +289 -0
  4. data/README.md +186 -0
  5. data/lib/gubbins/shell.rb +4 -0
  6. data/lib/shell/all.rb +34 -0
  7. data/lib/shell/base_64.rb +40 -0
  8. data/lib/shell/clam_av.rb +68 -0
  9. data/lib/shell/command.rb +1400 -0
  10. data/lib/shell/convert.rb +312 -0
  11. data/lib/shell/errors.rb +89 -0
  12. data/lib/shell/exiftool.rb +15 -0
  13. data/lib/shell/file.rb +84 -0
  14. data/lib/shell/ghostscript.rb +239 -0
  15. data/lib/shell/identify.rb +111 -0
  16. data/lib/shell/img2_pdf.rb +47 -0
  17. data/lib/shell/magick.rb +111 -0
  18. data/lib/shell/open_ssl.rb +26 -0
  19. data/lib/shell/optional_dependencies.rb +36 -0
  20. data/lib/shell/path.rb +40 -0
  21. data/lib/shell/pdf_detach.rb +86 -0
  22. data/lib/shell/pdffonts.rb +73 -0
  23. data/lib/shell/pdfimages.rb +48 -0
  24. data/lib/shell/pdfinfo.rb +79 -0
  25. data/lib/shell/pdftocairo.rb +24 -0
  26. data/lib/shell/pdftotext.rb +32 -0
  27. data/lib/shell/ping.rb +50 -0
  28. data/lib/shell/power_array.rb +42 -0
  29. data/lib/shell/seven_zip.rb +142 -0
  30. data/lib/shell/tesseract.rb +120 -0
  31. data/lib/shell/testing/mock/shell/clam_av.rb +12 -0
  32. data/lib/shell/testing/mock/shell/command.rb +241 -0
  33. data/lib/shell/testing/mock/shell/configurator.rb +223 -0
  34. data/lib/shell/testing/mock/shell/convert.rb +12 -0
  35. data/lib/shell/testing/mock/shell/file.rb +12 -0
  36. data/lib/shell/testing/mock/shell/ghostscript.rb +13 -0
  37. data/lib/shell/testing/mock/shell/identify.rb +11 -0
  38. data/lib/shell/testing/mock/shell/open_ssl.rb +11 -0
  39. data/lib/shell/testing/mock/shell/tesseract.rb +12 -0
  40. data/lib/shell/testing/mock/shell/unzip.rb +20 -0
  41. data/lib/shell/testing/mock/shell/zip.rb +11 -0
  42. data/lib/shell/testing.rb +15 -0
  43. data/lib/shell/tiff_2_pdf.rb +19 -0
  44. data/lib/shell/unzip.rb +137 -0
  45. data/lib/shell/version.rb +5 -0
  46. data/lib/shell/zbar.rb +123 -0
  47. data/lib/shell/zip.rb +52 -0
  48. data/lib/shell.rb +16 -0
  49. metadata +116 -0
@@ -0,0 +1,312 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "../shell"
4
+
5
+ module Shell
6
+ class Convert < Command
7
+ command_path `which convert`
8
+ option_prefix "-"
9
+ transform_options histogram: "histogram:#VALUE#",
10
+ repage: "+repage",
11
+ alpha_off: "-alpha",
12
+ kernel: "#VALUE#"
13
+
14
+ def self.resample(input:, output: nil, ppi:, **kargs)
15
+ output ||= input
16
+
17
+ exec input: input, output: output, resample: ppi, **kargs
18
+ end
19
+
20
+ # Resize an image so that no side is larger than `x` and `y`
21
+ #
22
+ # @param input [Pathname, Fs::File, String]
23
+ # @param output [Pathname, Fs::File, String] operates in-place if omitted
24
+ # @param x [Integer] maximum image width
25
+ # @param y [Integer] maximum image height
26
+ # @option **kargs passed straight through to `convert`
27
+ # @return [Shell::Command::Result]
28
+ def self.resize(input:, output: nil, x:, y:, **kargs)
29
+ output ||= input
30
+
31
+ exec input: input, output: output, resize: "#{x}x#{y}", **kargs
32
+ end
33
+
34
+ def self.thumbnail(input:, output: nil, size: "x300", **kargs)
35
+ output ||= input
36
+
37
+ exec input: input, output: output, thumbnail: size, **kargs
38
+ end
39
+
40
+ def self.auto_orient(input:, output: nil)
41
+ output ||= input
42
+
43
+ exec(input: input, output: output, auto_orient: nil)
44
+ end
45
+
46
+ # Removes the alpha channel, blending transparent areas onto white
47
+ #
48
+ # Also turns an image with a fully opaque alpha channel into a plain RGB one.
49
+ # `-flatten` would not do that: it keeps the channel.
50
+ #
51
+ # @param input [Pathname, String, Fs::File]
52
+ # @param output [Pathname, String, Fs::File, nil] overwrites `input` if `nil`
53
+ # @return [Shell::Command::Result]
54
+ def self.remove_alpha(input:, output: nil)
55
+ output ||= input
56
+
57
+ # `-alpha` is given twice, which a Hash of options cannot express; `alpha_off`
58
+ # is the second one.
59
+ exec(input: input, output: output, background: "white", alpha: "remove", alpha_off: "off")
60
+ end
61
+
62
+ def self.rotate(input:, output: nil, degrees:, **kargs)
63
+ output ||= input
64
+
65
+ exec input: input, output: output, rotate: degrees, **kargs
66
+ end
67
+
68
+ # Converts `input` image into a monochrome, dithered `output`
69
+ #
70
+ # @param input [Pathname, String, Fs::File]
71
+ # @param output [Pathname, String, Fs::File]
72
+ # @return [Shell::Command::Result]
73
+ def self.monochrome(input:, output: nil, **kargs)
74
+ exec input: input, output: output, monochrome: nil, **kargs
75
+ end
76
+
77
+ # Converts `input` into a dithered monochrome image and counts
78
+ # the ratio between black and white pixels
79
+ #
80
+ # @param input [Pathname, String, Fs::File]
81
+ # @return [Shell::Command::Result]
82
+ # `Result#value` [Hash{Symbol=>Float}] `{ black: Float, white: Float }`
83
+ def self.bw_ratio(input:)
84
+ exec(
85
+ input: input,
86
+ monochrome: nil,
87
+ format: "%c",
88
+ histogram: "info:-"
89
+ ).on_success do |result|
90
+ black_count =
91
+ result.stdout
92
+ .split("\n")
93
+ .find { |l| l.include?("#000000") }
94
+ &.strip
95
+ &.split(":")
96
+ &.first
97
+ &.to_i || 0
98
+
99
+ white_count =
100
+ result.stdout
101
+ .split("\n")
102
+ .find { |l| l.include?("#FFFFFF") }
103
+ &.strip
104
+ &.split(":")
105
+ &.first
106
+ &.to_i || 0
107
+
108
+ total = black_count + white_count
109
+
110
+ result.value =
111
+ {
112
+ black: black_count.fdiv(total) * 100,
113
+ white: white_count.fdiv(total) * 100
114
+ }
115
+ end
116
+ end
117
+
118
+ # Detects and corrects small-angle skew (eg. a receipt placed
119
+ # slightly crooked on a flatbed scanner)
120
+ #
121
+ # `background: "white"` fills the corners newly exposed by rotation - unlike
122
+ # `autocrop`'s `virtual_pixel: :edge`, replicating edge pixels here would
123
+ # smear real content into those corners instead of leaving clean background.
124
+ # `threshold` is ImageMagick's own suggested default for this operator;
125
+ # validated against 5 real scanned receipts (detected angles ranged -6..+3
126
+ # degrees, all visually correct).
127
+ #
128
+ # Run this before `autocrop`, not after: a skewed page always leaves
129
+ # triangular background wedges in the corners of an axis-aligned crop box,
130
+ # and diagonal content near the page edge otherwise keeps `autocrop` from
131
+ # trimming as tightly as it safely could.
132
+ #
133
+ # @param input [Pathname, String, Fs::File]
134
+ # @param output [Pathname, String, Fs::File, nil] overwrites `input` if `nil`
135
+ # @param threshold [String] passed to `-deskew`
136
+ # @return [Shell::Command::Result]
137
+ # `Result#value` [Float] the detected skew angle in degrees
138
+ def self.deskew(input:, output: nil, threshold: "40%%")
139
+ output ||= input
140
+
141
+ exec(
142
+ input: input,
143
+ output: output,
144
+ background: "white",
145
+ deskew: threshold,
146
+ print: "%[deskew:angle]",
147
+ repage: nil
148
+ ).on_success do |result|
149
+ result.value = result.stdout.to_f
150
+ end
151
+ end
152
+
153
+ # Automatically crop `input` by removing surrounding empty space
154
+ #
155
+ # Assumes `input` has already been through `enhance_contrast`: stretching
156
+ # the contrast pushes the background towards uniform white and the content
157
+ # towards uniform black, so that {.content_bounds} can tell them apart with
158
+ # a fixed threshold. Without that pre-pass, how much margin can be trimmed
159
+ # before real content starts getting cut varies wildly per document
160
+ # (observed safe anywhere between 4% and 11% on scanned receipts, depending
161
+ # on print contrast and scan noise).
162
+ #
163
+ # The crop box comes from {.content_bounds}, which ignores specks of
164
+ # scanner dust. A plain `-trim` cannot: a single dark speck near the edge
165
+ # of an otherwise empty A4 scan keeps the whole margin. Blurring the image
166
+ # first does not help either, since it smears thin or faint content
167
+ # (barcodes, faint ink) towards the background colour.
168
+ #
169
+ # An image without any content is left as it is.
170
+ #
171
+ # @param input [Pathname, String, Fs::File]
172
+ # @param output [Pathname, String, Fs::File, nil] overwrites `input` if `nil`
173
+ # @option kargs see {.content_bounds}
174
+ # @return [Shell::Command::Result]
175
+ def self.autocrop(input:, output: nil, **kargs)
176
+ output ||= input
177
+
178
+ bounds = content_bounds(input: input, **kargs)
179
+ return bounds if bounds.failure?
180
+
181
+ if bounds.value
182
+ exec(input: input, output: output, crop: bounds.value, repage: nil)
183
+ else
184
+ exec(input: input, output: output, repage: nil)
185
+ end
186
+ end
187
+
188
+ # Finds the box around the content of `input`, ignoring specks of dust
189
+ #
190
+ # Works on a throwaway copy: the dark pixels are dilated by `link_radius`,
191
+ # which fuses the characters of a text line into a single blob, and every
192
+ # blob smaller than `speck_area` is then discarded. What remains is real
193
+ # content, and its bounding box is returned. The dilation leaves a margin
194
+ # of about `link_radius` pixels around the content, which is a welcome
195
+ # safety margin against clipping.
196
+ #
197
+ # The defaults assume 300 DPI scans, and
198
+ # `enhance_contrast`ed input. Measured on scanned receipts, dust specks
199
+ # come out below 1,800 px² after dilation, while the smallest real text
200
+ # blobs (a few words, right-aligned amounts) start at around 4,600 px². So
201
+ # `speck_area` sits in the gap between the two.
202
+ #
203
+ # @param input [Pathname, String, Fs::File]
204
+ # @param speck_area [Integer] area in px² below which a dilated blob is dust
205
+ # @param link_radius [Integer] dilation radius in px
206
+ # @return [Shell::Command::Result]
207
+ # `Result#value` [String, nil] an ImageMagick geometry (`WxH+X+Y`), or `nil`
208
+ # if there is no content
209
+ def self.content_bounds(input:, speck_area: 3000, link_radius: 15)
210
+ exec(
211
+ input: input,
212
+ threshold: "60%%",
213
+ negate: nil,
214
+ morphology: "Dilate",
215
+ kernel: "Disk:#{link_radius}",
216
+ define: "connected-components:area-threshold=#{speck_area}",
217
+ connected_components: 8,
218
+ format: "%@",
219
+ output: "info:"
220
+ ).on_success do |result|
221
+ geometry = result.stdout[/\d+x\d+[+-]\d+[+-]\d+/]
222
+
223
+ # A blank image reports an empty box ("0x0+W+H") rather than none at all
224
+ result.value = geometry unless geometry.nil? || geometry.start_with?("0x")
225
+ end
226
+ end
227
+
228
+ # Adds a solid-colored border around `input`
229
+ #
230
+ # Meant to run after `autocrop`: Tesseract's LSTM engine reads text with
231
+ # some surrounding context, and a tight crop can leave content flush
232
+ # against the image edge with none - confirmed empirically to visibly
233
+ # affect OCR accuracy (not just at the touching edge, but elsewhere on
234
+ # the page too, presumably because the missing context shifts the
235
+ # engine's line segmentation). `size` of 20px comfortably fixed this on
236
+ # the one case we found actually touching an edge, without meaningfully
237
+ # affecting `autocrop`-based measurements taken afterwards.
238
+ #
239
+ # @param input [Pathname, String, Fs::File]
240
+ # @param output [Pathname, String, Fs::File, nil] overwrites `input` if `nil`
241
+ # @param size [Integer] border width in pixels, applied to all four sides
242
+ # @return [Shell::Command::Result]
243
+ def self.pad(input:, output: nil, size: 20)
244
+ output ||= input
245
+
246
+ exec(input: input, output: output, bordercolor: "white", border: "#{size}x#{size}")
247
+ end
248
+
249
+ # Increases contrast to improve readability of low-contrast printouts
250
+ # (eg. thermal receipts, whose print fades toward light gray rather
251
+ # than staying a clear black)
252
+ #
253
+ # Converts to grayscale first rather than stretching each color channel
254
+ # independently, since a per-channel stretch shifts the color balance of
255
+ # any colored content (logos, stamps) - we only care about text/number
256
+ # legibility here, not color fidelity.
257
+ #
258
+ # `threshold` clips this percentage of the darkest and lightest pixels
259
+ # before stretching the remainder across the full black-to-white range.
260
+ # Clipping (rather than a naive min/max stretch, ie. `-auto-level`) makes
261
+ # this robust against a handful of outlier pixels (eg. true-black barcode
262
+ # ink, JPEG noise) that would otherwise anchor the stretch and prevent it
263
+ # from doing anything - confirmed empirically: `-auto-level` and
264
+ # `-sigmoidal-contrast` both left 5 real scanned thermal receipts visually
265
+ # unchanged, while `-contrast-stretch 1%x1%` made every one of them crisp
266
+ # black-on-white with no visible loss of content.
267
+ #
268
+ # @param input [Pathname, String, Fs::File]
269
+ # @param output [Pathname, String, Fs::File, nil] overwrites `input` if `nil`
270
+ # @param threshold [String] percentage of pixels clipped at each end
271
+ # @return [Shell::Command::Result]
272
+ def self.enhance_contrast(input:, output: nil, threshold: "1%%")
273
+ output ||= input
274
+
275
+ exec(input: input, output: output, colorspace: "Gray", contrast_stretch: "#{threshold}x#{threshold}")
276
+ end
277
+
278
+ private
279
+
280
+ # ImageMagick uses a more peculiar argument format in the form of
281
+ # `convert input_file <options> output_file`, so we overload the
282
+ # command builder to automatically put the `:input` karg in front
283
+ # and append the `:output` karg at the end.
284
+ #
285
+ # TODO enable a more elegant approach to complex custom argument
286
+ # ordering somehow.
287
+ def build_command_arguments(*args, **kargs)
288
+ _positional_args, options =
289
+ preprocess_arguments(args, kargs)
290
+
291
+ input, output = nil
292
+
293
+ options.delete_if do |elem|
294
+ case elem.first
295
+ when :input
296
+ input = elem.last.respond_to?(:path) ? elem.last.path.to_s : elem.last.to_s
297
+ when :output
298
+ output = elem.last.respond_to?(:path) ? elem.last.path.to_s : elem.last.to_s
299
+ else
300
+ next false
301
+ end
302
+ end
303
+
304
+ command_arguments = stringify_options(options)
305
+
306
+ command_arguments.prepend(input) if input
307
+ command_arguments.append(output) if output
308
+
309
+ command_arguments
310
+ end
311
+ end
312
+ end
@@ -0,0 +1,89 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Shell
4
+ module Errors
5
+ # Base class for Shell command errors
6
+ #
7
+ # Raising one while handling another exception wraps that one as its
8
+ # `#cause`, as for any Ruby exception. To wrap one which is not the exception
9
+ # being handled, say so when raising: `raise Error.new("message"), cause: other`.
10
+ class Error < StandardError
11
+ # The backtrace of the exception which caused this one, if any
12
+ #
13
+ # Cleaned of framework and third-party code when running inside Rails,
14
+ # complete otherwise.
15
+ #
16
+ # @return [Array<String>]
17
+ def cause_application_backtrace
18
+ backtrace = Array(cause&.backtrace)
19
+
20
+ if defined?(Rails) && Rails.respond_to?(:backtrace_cleaner)
21
+ Rails.backtrace_cleaner.clean(backtrace)
22
+ else
23
+ backtrace
24
+ end
25
+ end
26
+ end
27
+
28
+ # Raised when a command exits and reports a failure
29
+ class CommandUnsuccessful < Error
30
+ end
31
+
32
+ # Raised when a command cannot be executed (IO errors, system call errors)
33
+ #
34
+ # Without a message of its own, it takes the one of the exception being handled.
35
+ class ExecutionError < Error
36
+ # @param message [#to_s, nil]
37
+ def initialize(message = nil)
38
+ super(message || $!&.message)
39
+ end
40
+ end
41
+
42
+ # Raised when the program behind a command is not there, eg. because it is not
43
+ # installed on this host
44
+ #
45
+ # The command path is looked up once, when the command class is loaded. If `which`
46
+ # found nothing then, the path is empty and stays so until the process restarts.
47
+ class CommandNotFound < ExecutionError
48
+ # @param command_class [Class] the {Shell::Command} subclass
49
+ # @param path [#to_s] the command path it was trying to run
50
+ def initialize(command_class:, path:)
51
+ super(
52
+ if path.to_s.empty?
53
+ "#{command_class.name} has no command path: `which` found no program when the class was loaded. " \
54
+ "Is it installed on this host, and on the PATH of this process?"
55
+ else
56
+ "#{command_class.name} cannot run #{path}: no such program. Is it installed on this host?"
57
+ end
58
+ )
59
+ end
60
+ end
61
+
62
+ # Raised when a wrapper needs a gem which gubbins-shell does not itself depend on
63
+ #
64
+ # These gems are listed under "Optional dependencies" in the README. The
65
+ # `LoadError` which revealed the gap is the `#cause`.
66
+ class DependencyMissing < Error
67
+ # @param gem_name [String]
68
+ # @param needed_by [String] what asked for it, eg. `"Shell::Zbar.scan"`
69
+ def initialize(gem_name:, needed_by:)
70
+ super("#{needed_by} needs the `#{gem_name}` gem, which gubbins-shell does not install itself. Add it to your Gemfile.")
71
+ end
72
+ end
73
+
74
+ # Raised when a command exceeds its timeout limit
75
+ class CommandTimeout < Error
76
+ attr_reader :command, :timeout_seconds, :pid
77
+
78
+ # @param command [String] the full command that was executed
79
+ # @param timeout [Numeric] the timeout in seconds
80
+ # @param pid [Integer, nil] the process ID if available
81
+ def initialize(command:, timeout:, pid: nil)
82
+ @command = command
83
+ @timeout_seconds = timeout
84
+ @pid = pid
85
+ super("Command timed out after #{timeout}s: #{command}")
86
+ end
87
+ end
88
+ end
89
+ end
@@ -0,0 +1,15 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "../shell"
4
+
5
+ module Shell
6
+ class Exiftool < Command
7
+ command_path `which exiftool`
8
+ option_prefix "-"
9
+ positional_parameters :last
10
+
11
+ def self.strip_icc(input:, **kargs)
12
+ exec "-ICC_PROFILE=", input
13
+ end
14
+ end
15
+ end
data/lib/shell/file.rb ADDED
@@ -0,0 +1,84 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "active_support"
4
+ require "active_support/core_ext/object/blank"
5
+ require_relative "../shell"
6
+
7
+ module Shell
8
+ class File < Command
9
+ command_path `which file`
10
+
11
+ class Result < Shell::Command::Result
12
+ # `file` returns successful exit codes even on filesystem errors, such as
13
+ # "file not found". There's an `-E` flag to change that, but it's not
14
+ # universally supported.
15
+ #
16
+ # @return [Boolean]
17
+ def success?
18
+ return false if stdout && stdout.start_with?("cannot open")
19
+
20
+ super
21
+ end
22
+
23
+ # Information returned from the command about an error situation
24
+ #
25
+ # @return [String]
26
+ def error_output
27
+ stderr.present? ? stderr : stdout
28
+ end
29
+ end
30
+
31
+ # Detect the files MIME type and encoding
32
+ #
33
+ # @param filename [Pathname, String, Fs::File]
34
+ # @return [Shell::Command::Result]
35
+ # `Result#value` [Hash{Symbol=>String}]
36
+ def self.magic(filename)
37
+ exec(filename, :b, :mime_type, :mime_encoding).on_success do |result|
38
+ mime_type =
39
+ result.stdout
40
+ .split(";")
41
+ .first
42
+
43
+ mime_encoding =
44
+ result.stdout
45
+ .split("=")
46
+ .last
47
+ .chomp
48
+
49
+ result.value = {
50
+ mime_type: mime_type,
51
+ mime_encoding: mime_encoding
52
+ }
53
+ end
54
+ end
55
+
56
+ # Detect the files MIME type
57
+ #
58
+ # @param filename [Pathname, String, Fs::File]
59
+ # @return [Shell::Command::Result]
60
+ # `Result#value` [String]
61
+ def self.mime_type(filename)
62
+ exec(filename, :b, :mime_type).on_success do |result|
63
+ result.value =
64
+ result.stdout
65
+ .chomp
66
+ end
67
+ end
68
+
69
+ # Detect the files MIME encoding
70
+ #
71
+ # @param filename [Pathname, String, Fs::File]
72
+ # @return [Shell::Command::Result]
73
+ # `Result#value` [String]
74
+ def self.mime_encoding(filename)
75
+ exec(filename, :b, :mime_encoding).on_success do |result|
76
+ result.value =
77
+ result.stdout
78
+ .split("=")
79
+ .last
80
+ .chomp
81
+ end
82
+ end
83
+ end
84
+ end