### Initialize and Test alpr_cam

Source: https://github.com/kaospr/alpr_cam/blob/main/README.md

Use these commands to prepare the local development environment and verify the installation.

```bash
git clone <repo-url>
cd alpr_cam
bundle install
bundle exec rake test
```

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

### Scanner Initialization and Execution

Source: https://github.com/kaospr/alpr_cam/blob/main/docs/superpowers/specs/2026-04-16-alpr-cam-gem-design.md

Initializes the scanner with camera and recognition settings and starts the capture-recognize loop.

```APIDOC
## Scanner.new

### Description
Initializes a new scanner instance with configuration for the camera device and OpenALPR parameters.

### Parameters
#### Options
- **device** (String) - Optional - V4L2 camera device path (default: "/dev/video0")
- **interval** (Float) - Optional - Seconds between frame captures (default: 1.0)
- **country** (String) - Optional - ALPR country code (default: "eu")
- **config** (String) - Optional - Path to openalpr config file (default: "/etc/openalpr/openalpr.conf")
- **top_n** (Integer) - Optional - Max number of candidate plates (default: 10)

## Scanner#scan

### Description
Starts the capture-recognize loop. This method blocks the calling thread and yields a PlateResult object for each detected plate.

### Parameters
- **block** (Proc) - Required - A block to receive PlateResult objects.

## Scanner#stop

### Description
Sets the internal running state to false to break the scan loop on the next iteration.
```

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

### Install alpr_cam

Source: https://github.com/kaospr/alpr_cam/blob/main/README.md

Add the gem to your project or install it directly via the command line.

```ruby
gem "alpr_cam"
```

```bash
gem install alpr_cam
```

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

### Run the Recognition Loop

Source: https://context7.com/kaospr/alpr_cam/llms.txt

Starts a blocking loop to capture frames and yield detected plates. Frames without detected plates are skipped.

```ruby
require "alpr_cam"

scanner = AlprCam::Scanner.new(
  device: "/dev/video0",
  interval: 0.5,
  country: "us"
)

scanner.scan do |result|
  puts "=" * 40
  puts "Plate Detected: #{result.plate}"
  puts "Confidence: #{result.confidence}%"
  puts "Region: #{result.region}"
  puts "Timestamp: #{result.timestamp}"
  puts "Image: #{result.image_path}"

  # Access alternative readings
  result.candidates.each do |candidate|
    puts "  Alternative: #{candidate[:plate]} (#{candidate[:confidence]}%)"
  end
end
```

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

### Initialize and Scan with AlprCam Scanner

Source: https://github.com/kaospr/alpr_cam/blob/main/docs/superpowers/specs/2026-04-16-alpr-cam-gem-design.md

Instantiate the AlprCam::Scanner with desired options and start the continuous scanning process. The block provided will be executed for each detected license plate.

```ruby
require "alpr_cam"

scanner = AlprCam::Scanner.new(
  device: "/dev/video0",
  interval: 1.0,
  country: "eu",
  config: "/etc/openalpr/openalpr.conf",
  top_n: 10
)

scanner.scan do |result|
  puts "#{result.plate} (#{result.confidence}%)"
end
```

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

### Run ALPR Cam Scanner

Source: https://github.com/kaospr/alpr_cam/blob/main/docs/superpowers/specs/2026-04-16-alpr-cam-gem-design.md

Execute the ALPR Cam scanner to detect and print license plates from a camera feed. Requires the gem to be installed.

```ruby
ruby -e "require 'alpr_cam'; AlprCam::Scanner.new.scan { |r| puts r.plate }"
```

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

### Scanner Error Handling

Source: https://context7.com/kaospr/alpr_cam/llms.txt

Utilize `AlprCam::Scanner` with a block for real-time scanning. This example demonstrates comprehensive error handling for `AlprCam::CaptureError`, `AlprCam::RecognitionError`, and a general `AlprCam::Error` catch-all.

```ruby
require "alpr_cam"

scanner = AlprCam::Scanner.new(device: "/dev/video0")

begin
  scanner.scan do |result|
    puts "#{result.plate} detected"

    # Your processing logic...
    send_to_database(result.plate, result.confidence)
  end
rescue AlprCam::CaptureError => e
  # GStreamer frame capture failed
  # - Device not found or busy
  # - gst-launch-1.0 not installed
  # - Capture timed out (10s limit)
  STDERR.puts "Camera error: #{e.message}"
  exit 1
rescue AlprCam::RecognitionError => e
  # OpenALPR processing failed
  # - alpr binary not found
  # - Invalid JSON output
  # - Config file not found
  STDERR.puts "ALPR error: #{e.message}"
  exit 2
rescue AlprCam::Error => e
  # Catch-all for any gem error
  STDERR.puts "AlprCam error: #{e.message}"
  exit 3
end
```

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

### Build and Run Docker Image

Source: https://context7.com/kaospr/alpr_cam/llms.txt

Instructions for building the ALPR Cam Docker image and running the scanner within a container, including attaching the camera device and executing Ruby scripts.

```bash
# Build the Docker image
docker build -t alpr_cam .

# Run with camera device attached
docker run --device=/dev/video0 -it alpr_cam ruby -e "
  require 'alpr_cam'

  trap('INT') { exit }

  scanner = AlprCam::Scanner.new(interval: 0.5)
  scanner.scan do |r|
    puts \"[\#{Time.now}] \#{r.plate} (\#{r.confidence.round(1)}%)\" 
  end
"

# Run tests inside Docker
docker run -it alpr_cam bundle exec rake test

# Interactive shell for debugging
docker run --device=/dev/video0 -it alpr_cam /bin/bash
```

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

### Initialize and run basic scanner

Source: https://github.com/kaospr/alpr_cam/blob/main/README.md

Configure the scanner with device, interval, and country settings, then process detected plates within a block.

```ruby
require "alpr_cam"

scanner = AlprCam::Scanner.new(
  device: "/dev/video0",
  interval: 1.0,
  country: "eu"
)

scanner.scan do |result|
  puts "Plate: #{result.plate} (#{result.confidence}%)"
  puts "Region: #{result.region}"
  puts "Candidates: #{result.candidates}"
end
```

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

### Create and Use Recognizer Instance

Source: https://context7.com/kaospr/alpr_cam/llms.txt

Instantiate `AlprCam::Recognizer` to run OpenALPR on image files and parse results. Configure country, config path, and top N results. Handles `AlprCam::RecognitionError` for issues like missing OpenALPR binary or invalid image files.

```ruby
require "alpr_cam"

# Create a recognizer with specific settings
recognizer = AlprCam::Recognizer.new(
  country: "eu",
  config: "/etc/openalpr/openalpr.conf",
  top_n: 5
)

begin
  # Process an image file
  results = recognizer.recognize("/path/to/image.jpg")

  if results.empty?
    puts "No plates detected in image"
  else
    results.each do |result|
      puts "Found plate: #{result.plate} (#{result.confidence}%)"
    end
  end

rescue AlprCam::RecognitionError => e
  puts "Recognition failed: #{e.message}"
  # Possible causes:
  # - OpenALPR not installed (alpr binary not found)
  # - Invalid config file path
  # - Invalid or corrupted image file
end
```

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

### Docker operations

Source: https://github.com/kaospr/alpr_cam/blob/main/README.md

Commands for building the Docker image, running the scanner with device access, and executing tests.

```bash
docker build -t alpr_cam .
```

```bash
docker run --device=/dev/video0 -it alpr_cam ruby -e "
  require 'alpr_cam'
  AlprCam::Scanner.new.scan { |r| puts r.plate }
"
```

```bash
docker run -it alpr_cam bundle exec rake test
```

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

### Create and Use Frame Capture Instance

Source: https://context7.com/kaospr/alpr_cam/llms.txt

Instantiate `AlprCam::FrameCapture` to capture a single frame from a specified device. The captured frame is saved as a JPEG file, and its path is returned. Ensure to clean up the temporary file after processing.

```ruby
capture = AlprCam::FrameCapture.new(device: "/dev/video0")

begin
  # Capture a single frame - returns path to JPEG file
  image_path = capture.capture
  puts "Frame saved to: #{image_path}"

  # Process the image as needed...

  # Clean up temp file when done
  File.delete(image_path) if File.exist?(image_path)

rescue AlprCam::CaptureError => e
  puts "Capture failed: #{e.message}"
  # Possible causes:
  # - Device not available or busy
  # - GStreamer not installed (gst-launch-1.0 not found)
  # - Capture timed out after 10 seconds
end
```

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

### Initialize the License Plate Scanner

Source: https://context7.com/kaospr/alpr_cam/llms.txt

Creates a new scanner instance for a specific camera device. Configuration options include capture interval, country code, and OpenALPR settings.

```ruby
require "alpr_cam"

# Create a scanner with custom configuration
scanner = AlprCam::Scanner.new(
  device: "/dev/video0",           # V4L2 camera device path
  interval: 1.0,                   # Seconds between frame captures
  country: "eu",                   # ALPR country code (eu, us, au, etc.)
  config: "/etc/openalpr/openalpr.conf",  # OpenALPR config file
  top_n: 10                        # Max number of candidate plates returned
)

# Or use defaults (device: /dev/video0, interval: 1.0, country: eu)
scanner = AlprCam::Scanner.new
```

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

### Capture Frame using GStreamer CLI

Source: https://github.com/kaospr/alpr_cam/blob/main/docs/superpowers/specs/2026-04-16-alpr-cam-gem-design.md

This command-line invocation uses GStreamer to capture a single frame from a V4L2 camera device, convert it, encode it as JPEG, and save it to a temporary file.

```bash
gst-launch-1.0 v4l2src device=/dev/video0 num-buffers=1 ! videoconvert ! jpegenc ! filesink location=/tmp/alpr_XXXX.jpg
```

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

### Recognize License Plates using Alpr CLI

Source: https://github.com/kaospr/alpr_cam/blob/main/docs/superpowers/specs/2026-04-16-alpr-cam-gem-design.md

This command-line invocation uses the `alpr` tool to perform license plate recognition on a given image file. It outputs results in JSON format, specifies the country code, configuration file, and the maximum number of candidate plates to return.

```bash
alpr -j -c eu --config /etc/openalpr/openalpr.conf -n 10 /path/to/frame.jpg
```

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

### Capture Single Frames

Source: https://context7.com/kaospr/alpr_cam/llms.txt

Uses the low-level FrameCapture class to grab a single frame from a V4L2 device with a built-in timeout.

```ruby
require "alpr_cam"
```

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

### Handle recognition and capture errors

Source: https://github.com/kaospr/alpr_cam/blob/main/README.md

Rescue specific errors during the scanning process to handle GStreamer or ALPR CLI failures.

```ruby
scanner.scan do |result|
  puts result.plate
rescue AlprCam::CaptureError => e
  # GStreamer frame capture failed or timed out
  puts "Capture error: #{e.message}"
rescue AlprCam::RecognitionError => e
  # alpr CLI failed or returned invalid output
  puts "Recognition error: #{e.message}"
end
```

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

### Access PlateResult Data

Source: https://context7.com/kaospr/alpr_cam/llms.txt

Demonstrates how to access attributes of the PlateResult object yielded by the scanner, including confidence scores and candidate readings.

```ruby
require "alpr_cam"

scanner = AlprCam::Scanner.new

scanner.scan do |result|
  # Access all PlateResult attributes
  plate_text = result.plate          # String: "ABC1234"
  confidence = result.confidence     # Float: 94.5
  region = result.region             # String: "us-ca"
  candidates = result.candidates     # Array: [{plate: "A8C1234", confidence: 89.2}, ...]
  timestamp = result.timestamp       # Time: 2024-01-15 14:32:18 -0500
  image_path = result.image_path     # String: "/tmp/alpr_frame_xxx.jpg"

  # Filter by confidence threshold
  if result.confidence > 90
    puts "High-confidence detection: #{result.plate}"
  end

  # Process candidates for fuzzy matching
  all_readings = [result.plate] + result.candidates.map { |c| c[:plate] }
  puts "All possible readings: #{all_readings.join(', ')}"
end
```

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

### Stop the scanner loop

Source: https://github.com/kaospr/alpr_cam/blob/main/README.md

Use the stop method to break the blocking scan loop, typically triggered by a signal handler.

```ruby
scanner = AlprCam::Scanner.new

trap("INT") { scanner.stop }

scanner.scan do |result|
  puts result.plate
end
```

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

### Stop the Recognition Loop

Source: https://context7.com/kaospr/alpr_cam/llms.txt

Gracefully terminates the scanner loop by setting an internal flag. This is typically triggered by signal handlers like SIGINT or SIGTERM.

```ruby
require "alpr_cam"

scanner = AlprCam::Scanner.new(device: "/dev/video0")

# Stop on Ctrl+C (SIGINT)
trap("INT") { scanner.stop }

# Stop on SIGTERM (for Docker/systemd)
trap("TERM") { scanner.stop }

puts "Starting scanner... Press Ctrl+C to stop"

scanner.scan do |result|
  puts "[#{result.timestamp}] #{result.plate} (#{result.confidence}%)"
end

puts "Scanner stopped gracefully"
```

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

### PlateResult Data Model

Source: https://github.com/kaospr/alpr_cam/blob/main/docs/superpowers/specs/2026-04-16-alpr-cam-gem-design.md

The structure of the object yielded by the scanner when a license plate is detected.

```APIDOC
### PlateResult
- **plate** (String) - Best match plate text
- **confidence** (Float) - Confidence 0-100
- **region** (String) - Detected region
- **candidates** (Array) - Alternative plate readings (Array of Hash {plate:, confidence:})
- **timestamp** (Time) - When the frame was captured
- **image_path** (String) - Path to the captured frame file
```

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