### Install Grim Gem

Source: https://github.com/jonmagic/grim/blob/master/README.md

This command installs the Grim gem using RubyGems. Ensure you have Ruby and RubyGems set up on your system.

```bash
$ gem install grim
```

--------------------------------

### Install Prerequisites using Homebrew (macOS)

Source: https://github.com/jonmagic/grim/blob/master/README.md

This command installs the necessary dependencies (Ghostscript, ImageMagick, and xpdf) on macOS using the Homebrew package manager. These tools are required for Grim to function correctly.

```bash
$ brew install ghostscript imagemagick xpdf
```

--------------------------------

### Install Grim and System Dependencies

Source: https://context7.com/jonmagic/grim/llms.txt

Instructions for installing the Grim gem and its system-level dependencies (Ghostscript, ImageMagick, xpdf) on macOS using Homebrew.

```bash
# Install system dependencies (macOS)
brew install ghostscript imagemagick xpdf

# Install the gem
gem install grim
```

--------------------------------

### Specify ImageMagick and Ghostscript Paths (Ruby)

Source: https://github.com/jonmagic/grim/blob/master/README.md

Shows how to configure Grim to use specific paths for ImageMagick's 'convert' and Ghostscript executables. This is useful when multiple versions are installed or they are not in the system's PATH.

```ruby
# specifying one processor with specific ImageMagick and GhostScript paths
Grim.processor =  Grim::ImageMagickProcessor.new({:imagemagick_path => "/path/to/convert", :ghostscript_path => "/path/to/gs"})

# multiple processors with fallback if first fails, useful if you need multiple versions of convert/gs
Grim.processor = Grim::MultiProcessor.new([
  Grim::ImageMagickProcessor.new({:imagemagick_path => "/path/to/6.7/convert", :ghostscript_path => "/path/to/9.04/gs"}),
  Grim::ImageMagickProcessor.new({:imagemagick_path => "/path/to/6.6/convert", :ghostscript_path => "/path/to/9.02/gs"})
])

pdf = Grim.reap('/path/to/pdf')
```

--------------------------------

### Basic Grim PDF Usage (Ruby)

Source: https://github.com/jonmagic/grim/blob/master/README.md

Demonstrates the basic usage of the Grim gem in Ruby. It shows how to load a PDF, get the page count, save a specific page as an image, and extract text from a page.

```ruby
pdf   = Grim.reap("/path/to/pdf")         # returns Grim::Pdf instance for pdf
count = pdf.count                         # returns the number of pages in the pdf
png   = pdf[3].save('/path/to/image.png') # will return true if page was saved or false if not
text  = pdf[3].text                       # returns text as a String

pdf.each do |page|
  puts page.text
end
```

--------------------------------

### Configure Image Processor with Grim.processor=

Source: https://context7.com/jonmagic/grim/llms.txt

Explains how to set a custom image processor for Grim, allowing the specification of custom paths for ImageMagick and Ghostscript binaries. This is useful in environments where these tools are installed in non-standard locations.

```ruby
require 'grim'

# Use custom paths for ImageMagick and Ghostscript
Grim.processor = Grim::ImageMagickProcessor.new({
  imagemagick_path: "/usr/local/bin/convert",
  ghostscript_path: "/usr/local/bin/gs"
})
```

--------------------------------

### Iterate Over PDF Pages with Grim::Pdf#each

Source: https://context7.com/jonmagic/grim/llms.txt

Shows how to iterate over all pages in a PDF document using the `each` method, leveraging the `Enumerable` module. Examples include processing each page and using `map` and `select` methods.

```ruby
require 'grim'

pdf = Grim.reap("/path/to/document.pdf")

# Iterate through all pages
pdf.each do |page|
  puts "Page #{page.number}: #{page.text.length} characters"
end

# Use Enumerable methods
page_numbers = pdf.map { |page| page.number }
# => [1, 2, 3, 4, 5, ...]

# Find pages with specific content
pages_with_table = pdf.select { |page| page.text.include?("Table") }
```

--------------------------------

### Load PDF Document with Grim.reap

Source: https://context7.com/jonmagic/grim/llms.txt

Demonstrates how to load a PDF document using `Grim.reap`. It shows how to get the page count, access the PDF path, handle file not found errors, and specify custom paths for utilities like pdftotext.

```ruby
require 'grim'

# Load a PDF file
pdf = Grim.reap("/path/to/document.pdf")

# Get the number of pages
page_count = pdf.count
# => 25

# Access the PDF path
pdf.path
# => "/path/to/document.pdf"

# Error handling for missing files
begin
  pdf = Grim.reap("/nonexistent/file.pdf")
rescue Grim::PdfNotFound => e
  puts "PDF file not found: #{e.message}"
end

# With custom pdftotext path
pdf = Grim::Pdf.new("/path/to/document.pdf", pdftotext_path: "/usr/local/bin/pdftotext")
```

--------------------------------

### Access Individual PDF Pages with Grim::Pdf#[]

Source: https://context7.com/jonmagic/grim/llms.txt

Explains how to access individual pages of a loaded PDF using zero-based indexing with the `pdf[index]` syntax. It includes examples of retrieving page numbers and handling `Grim::PageNotFound` errors.

```ruby
require 'grim'

pdf = Grim.reap("/path/to/presentation.pdf")

# Access the first page (index 0)
first_page = pdf[0]
first_page.number
# => 1

# Access the fifth page (index 4)
fifth_page = pdf[4]
fifth_page.number
# => 5

# Error handling for invalid page index
begin
  page = pdf[100]  # Page doesn't exist
rescue Grim::PageNotFound => e
  puts "Page not found: #{e.message}"
end
```

--------------------------------

### Extract Text Content with Grim::Page#text

Source: https://context7.com/jonmagic/grim/llms.txt

Demonstrates how to extract text content from a PDF page using the `text` method, which utilizes pdftotext. It includes examples for extracting all text from a document, using specific flags like `-table`, and searching for content across pages.

```ruby
require 'grim'

pdf = Grim.reap("/path/to/document.pdf")

# Extract text from a page
text = pdf[0].text
# => "This is the text content from the first page.\n\n"

# Extract all text from document
full_text = pdf.map { |page| page.text }.join("\n---\n")

# Extract tabular data with -table flag
pdf = Grim.reap("/path/to/report.pdf")
table_text = pdf[0].text(flags: ["-table"])
# Preserves column alignment for tables

# Search for content across pages
pdf.each do |page|
  if page.text.include?("CONFIDENTIAL")
    puts "Found confidential content on page #{page.number}"
  end
end
```

--------------------------------

### Specify Windows Ghostscript Executable (Ruby)

Source: https://github.com/jonmagic/grim/blob/master/README.md

Demonstrates how to specify a Windows Ghostscript executable (e.g., gswin64c.exe) for Grim. Note that the directory containing the executable must still be in the system's PATH.

```ruby
# specifying another ghostscript executable, win64 in this example
# the ghostscript/bin folder still has to be in the PATH for this to work
Grim.processor =  Grim::ImageMagickProcessor.new({:ghostscript_path => "gswin64c.exe"})

pdf = Grim.reap('/path/to/pdf')
```

--------------------------------

### Save Page with Options (Ruby)

Source: https://github.com/jonmagic/grim/blob/master/README.md

Illustrates how to use the `save` method with various options to control the output image quality, size, density, and colorspace. These options allow fine-tuning the image generation process.

```ruby
pdf = Grim.reap("/path/to/pdf")
pdf[0].save('/path/to/image.png', {
  :width => 600,         # defaults to 1024
  :density => 72,        # defaults to 300
  :quality => 60,        # defaults to 90
  :colorspace => "CMYK", # defaults to "RGB"
  :alpha => "Activate"   # not used when not set
})
```

--------------------------------

### Configure Grim Logger (Ruby)

Source: https://github.com/jonmagic/grim/blob/master/README.md

Shows how to set a custom logger for Grim, enabling detailed logging of its operations, such as the imagemagick commands being executed. This is useful for debugging and understanding Grim's internal processes.

```ruby
require "logger"
Grim.logger = Logger.new($stdout).tap { |logger| logger.progname = 'Grim' }
Grim.processor = Grim::ImageMagickProcessor.new({:ghostscript_path => "/path/to/bin/gs"})
pdf = Grim.reap("/path/to/pdf")
pdf[3].save('/path/to/image.png')
# D, [2016-06-09T22:43:07.046532 #69344] DEBUG -- grim: Running imagemagick command
# D, [2016-06-09T22:43:07.046626 #69344] DEBUG -- grim: PATH=/path/to/bin:/usr/local/bin:/usr/bin
# D, [2016-06-09T22:43:07.046787 #69344] DEBUG -- grim: convert -resize 1024 -antialias -render -quality 90 -colorspace RGB -interlace none -density 300 /path/to/pdf /path/to/image.png
```

--------------------------------

### Configure File Logging for Grim

Source: https://context7.com/jonmagic/grim/llms.txt

Sets up Grim to log debug information to a specified file. This is useful for production environments where direct console output is not desired.

```ruby
require 'grim'

# File logging
Grim.logger = Logger.new("/var/log/grim.log")
```

--------------------------------

### Handle Grim PDF Processing Exceptions

Source: https://context7.com/jonmagic/grim/llms.txt

Demonstrates how to handle specific Grim exception classes like Grim::PdfNotFound, Grim::PageNotFound, Grim::PathMissing, and Grim::UnprocessablePage during PDF processing. This allows for graceful error management in the application.

```ruby
require 'grim'

def process_pdf(path, output_dir)
  begin
    pdf = Grim.reap(path)
  rescue Grim::PdfNotFound
    puts "Error: PDF file not found at #{path}"
    return false
  end

  pdf.each do |page|
    begin
      output = "#{output_dir}/page_#{page.number}.png"
      page.save(output)

    rescue Grim::PageNotFound
      puts "Error: Page #{page.number} does not exist"
    rescue Grim::PathMissing
      puts "Error: Output path is required"
    rescue Grim::UnprocessablePage => e
      puts "Error: Could not process page #{page.number}: #{e.message}"
    end
  end

  true
end

# Usage
process_pdf("/documents/report.pdf", "/output/images")
```

--------------------------------

### Configure Windows ImageMagick Processor for Grim

Source: https://context7.com/jonmagic/grim/llms.txt

Sets up Grim to use the ImageMagick processor on Windows, specifying the path to the Ghostscript executable. This is essential for Grim to process PDFs using ImageMagick on a Windows system.

```ruby
Grim.processor = Grim::ImageMagickProcessor.new({
  ghostscript_path: "gswin64c.exe"
})

pdf = Grim.reap("/path/to/document.pdf")
pdf[0].save("/output/page.png")
```

--------------------------------

### Configure Multiple Processors with Fallback in Grim

Source: https://context7.com/jonmagic/grim/llms.txt

Configures Grim to use multiple ImageMagick processors with different tool paths, enabling automatic fallback. This is useful when specific PDF files might require different versions of ImageMagick or Ghostscript to process correctly.

```ruby
require 'grim'

Grim.processor = Grim::MultiProcessor.new([
  Grim::ImageMagickProcessor.new({
    imagemagick_path: "/opt/imagemagick-7/bin/convert",
    ghostscript_path: "/opt/gs-9.50/bin/gs"
  }),
  Grim::ImageMagickProcessor.new({
    imagemagick_path: "/opt/imagemagick-6/bin/convert",
    ghostscript_path: "/opt/gs-9.20/bin/gs"
  }),
  Grim::ImageMagickProcessor.new
])

pdf = Grim.reap("/path/to/problematic.pdf")
pdf[0].save("/output/page.png")
```

--------------------------------

### Save PDF Page to Image with Grim::Page#save

Source: https://context7.com/jonmagic/grim/llms.txt

Details how to convert a specific PDF page into an image file (PNG, JPEG, etc.) using the `save` method. It covers basic saving, applying custom options like width, density, quality, and colorspace, and processing all pages to images.

```ruby
require 'grim'

pdf = Grim.reap("/path/to/document.pdf")

# Basic save to PNG
pdf[0].save("/output/page1.png")
# => true

# Save as JPEG with custom options
pdf[0].save("/output/page1.jpg", {
  width: 600,          # Output width in pixels (default: 1024)
  density: 72,         # DPI for rendering (default: 300)
  quality: 60,         # Image quality 1-100 (default: 90)
  colorspace: "CMYK",  # Color space (default: "RGB")
  alpha: "Activate"    # Alpha channel handling (optional)
})

# Process all pages to images
pdf.each do |page|
  output_path = "/output/page_#{page.number}.png"
  page.save(output_path, width: 800, quality: 85)
  puts "Saved #{output_path}"
end

# Error handling
begin
  pdf[0].save(nil)  # Empty path
rescue Grim::PathMissing => e
  puts "Path is required"
end

begin
  pdf[0].save("/output/page.png")
rescue Grim::UnprocessablePage => e
  puts "Failed to process page: #{e.message}"
end
```

--------------------------------

### Configure Debug Logging for Grim

Source: https://context7.com/jonmagic/grim/llms.txt

Enables debug logging for Grim by configuring a Logger object to output to standard output. This helps in tracking the commands Grim executes and diagnosing processing issues.

```ruby
require 'grim'
require 'logger'

Grim.logger = Logger.new($stdout).tap do |logger|
  logger.progname = 'Grim'
  logger.level = Logger::DEBUG
end

Grim.processor = Grim::ImageMagickProcessor.new({
  ghostscript_path: "/usr/local/bin/gs"
})

pdf = Grim.reap("/path/to/document.pdf")
pdf[0].save("/output/page.png")
```

--------------------------------

### Disable Logging in Grim

Source: https://context7.com/jonmagic/grim/llms.txt

Disables all logging for Grim by setting the logger to Grim::NullLogger. This is the default behavior and is useful when detailed logging is not required.

```ruby
require 'grim'

# Disable logging (default)
Grim.logger = Grim::NullLogger.new
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.