pura-jpeg 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b497cc2d62e912f13269111752139cdede385a5a4f0fb0a020743c9270f969a6
+  data.tar.gz: 6712cb8189a06cfd4ea1fe4af6c0dbd713d286f79acd29e24f0e9123c4f09843
+SHA512:
+  metadata.gz: 533b5753fb406eac2f2590b719cba7d1ab282ccbadf333fbb16b51bc35432b9e436552f85d9fd30336f6028b46f98fcfa879ce40d4957ee006591c60d99fa1d8
+  data.tar.gz: a4f52d7145e529abd3c12ea8363d5f36fc3853f3095c1f82f953dbe098eeabd4859422678a5bc68755beca89c4577e9c6571ee90ef8fd4d201fb0de4a422ed9b

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jpeg_pure contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,103 @@
+# pura-jpeg
+
+A pure Ruby JPEG decoder/encoder with zero C extension dependencies.
+
+Part of the **pura-*** series — pure Ruby image codec gems.
+
+## Features
+
+- Baseline JPEG decoding and encoding (SOF0)
+- Image resizing (bilinear / nearest-neighbor interpolation)
+- Huffman coding, fast integer IDCT/FDCT, YCbCr ↔ RGB conversion
+- 4:2:0, 4:2:2, and 4:4:4 chroma subsampling
+- No native extensions, no FFI, no external dependencies
+- CLI tool included
+
+## Installation
+
+```bash
+gem install pura-jpeg
+```
+
+## Usage
+
+```ruby
+require "pura-jpeg"
+
+# Decode
+image = Pura::Jpeg.decode("photo.jpg")
+image.width      #=> 1920
+image.height     #=> 1080
+image.pixels     #=> Raw RGB byte string
+
+# Resize
+thumb = image.resize(200, 200)
+fitted = image.resize_fit(800, 600)   # maintain aspect ratio
+
+# Encode
+Pura::Jpeg.encode(thumb, "thumb.jpg", quality: 80)
+```
+
+## CLI
+
+```bash
+pura-jpeg decode input.jpg --info
+pura-jpeg resize input.jpg --width 200 --height 200 --out thumb.jpg
+pura-jpeg resize input.jpg --fit 800x600 --out fitted.jpg
+```
+
+## Benchmark
+
+400×400 image, Ruby 4.0.2 + YJIT.
+
+### Decode
+
+| Decoder | Time | Language |
+|---------|------|----------|
+| jpeg-js (V8 JIT) | 39 ms | Pure JavaScript |
+| jpeg-js (`--jitless`) | 143 ms | Pure JavaScript (interpreter) |
+| ffmpeg (C) | 55 ms | C |
+| **pura-jpeg** | **304 ms** | **Pure Ruby** |
+| ptjd | 5,448 ms | Pure Tcl |
+
+### Encode
+
+| Encoder | Time | vs ffmpeg |
+|---------|------|-----------|
+| ffmpeg (C) | 62 ms | — |
+| **pura-jpeg** | **238 ms** | 3.8× slower |
+
+### Full pipeline (decode → resize → encode)
+
+| Operation | Time |
+|-----------|------|
+| Decode | 304 ms |
+| Encode (quality 85) | 243 ms |
+| Full pipeline | ~547 ms |
+
+pura-jpeg is **2× faster than ptjd** (Tcl) and within **2× of jpeg-js running without JIT**. These are the only three pure scripting-language JPEG implementations that exist — Python, Perl, PHP, and Lua all rely on C extensions.
+
+## Why pure Ruby?
+
+- **`gem install` and go** — no `brew install`, no `apt install`, no C compiler needed
+- **Works everywhere Ruby works** — CRuby, ruby.wasm, mruby, JRuby, TruffleRuby
+- **Edge/Wasm ready** — runs in Cloudflare Workers, browsers (via ruby.wasm), sandboxed environments where you can't install system libraries
+- **Perfect for dev/CI** — no ImageMagick or libvips setup. `rails new` → image upload → it just works
+- **Unix philosophy** — one format, one gem, composable
+
+## Related gems
+
+| Gem | Format | Status |
+|-----|--------|--------|
+| **pura-jpeg** | JPEG | ✅ Available |
+| [pura-png](https://github.com/komagata/pura-png) | PNG | ✅ Available |
+| [pura-bmp](https://github.com/komagata/pura-bmp) | BMP | ✅ Available |
+| [pura-gif](https://github.com/komagata/pura-gif) | GIF | ✅ Available |
+| [pura-tiff](https://github.com/komagata/pura-tiff) | TIFF | ✅ Available |
+| [pura-ico](https://github.com/komagata/pura-ico) | ICO | ✅ Available |
+| [pura-webp](https://github.com/komagata/pura-webp) | WebP | ✅ Available |
+| [pura-image](https://github.com/komagata/pura-image) | All formats | ✅ Available |
+
+## License
+
+MIT

data/bin/pura-jpeg

@@ -0,0 +1,222 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/pure-jpeg"
+
+def usage
+  puts <<~USAGE
+    Usage: pure-jpeg <command> [options]
+
+    Commands:
+      decode <input.jpg> [options]   Decode a JPEG file
+        --info                       Show image metadata
+        --out <file>                 Write raw RGB data to file
+
+      encode <input.rgb> [options]   Encode raw RGB data to JPEG
+        --width <n>                  Image width (required)
+        --height <n>                 Image height (required)
+        --quality <n>                JPEG quality 1-100 (default: 85)
+        --subsampling <type>         420 or 444 (default: 420)
+        --out <file>                 Output JPEG file (required)
+
+      resize <input.jpg> [options]   Resize a JPEG file
+        --width <n>                  Target width
+        --height <n>                 Target height
+        --fit <W>x<H>               Fit within bounds (maintain aspect ratio)
+        --fill <W>x<H>              Fill exact size (crop to fit)
+        --interpolation <type>       bilinear or nearest (default: bilinear)
+        --quality <n>                Output JPEG quality (default: 85)
+        --out <file>                 Output JPEG file (required)
+
+      benchmark <input.jpg>          Benchmark decoding vs system tools
+
+      version                        Show version
+  USAGE
+  exit 1
+end
+
+def cmd_decode(args)
+  input = nil
+  info_only = false
+  output = nil
+
+  i = 0
+  while i < args.size
+    case args[i]
+    when "--info"
+      info_only = true
+    when "--out"
+      i += 1
+      output = args[i]
+    else
+      input = args[i]
+    end
+    i += 1
+  end
+
+  usage unless input
+
+  unless File.exist?(input)
+    $stderr.puts "Error: file not found: #{input}"
+    exit 1
+  end
+
+  start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  image = Pure::Jpeg.decode(input)
+  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+
+  if info_only
+    puts "File:   #{input}"
+    puts "Width:  #{image.width}"
+    puts "Height: #{image.height}"
+    puts "Pixels: #{image.width * image.height}"
+    puts "Size:   #{File.size(input)} bytes"
+    puts "Decode: #{'%.3f' % elapsed}s"
+  elsif output
+    File.binwrite(output, image.pixels)
+    puts "Wrote #{image.pixels.bytesize} bytes of raw RGB to #{output}"
+    puts "Decode time: #{'%.3f' % elapsed}s"
+  else
+    puts "Decoded #{input}: #{image.width}x#{image.height} in #{'%.3f' % elapsed}s"
+  end
+end
+
+def cmd_encode(args)
+  input = nil
+  width = nil
+  height = nil
+  quality = 85
+  subsampling = :s420
+  output = nil
+
+  i = 0
+  while i < args.size
+    case args[i]
+    when "--width"
+      i += 1; width = args[i].to_i
+    when "--height"
+      i += 1; height = args[i].to_i
+    when "--quality"
+      i += 1; quality = args[i].to_i
+    when "--subsampling"
+      i += 1
+      subsampling = args[i] == "444" ? :s444 : :s420
+    when "--out"
+      i += 1; output = args[i]
+    else
+      input = args[i]
+    end
+    i += 1
+  end
+
+  unless input && width && height && output
+    $stderr.puts "Error: encode requires input file, --width, --height, and --out"
+    usage
+  end
+
+  unless File.exist?(input)
+    $stderr.puts "Error: file not found: #{input}"
+    exit 1
+  end
+
+  raw = File.binread(input)
+  image = Pure::Jpeg::Image.new(width, height, raw)
+
+  start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  size = Pure::Jpeg.encode(image, output, quality: quality, subsampling: subsampling)
+  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+
+  puts "Encoded #{width}x#{height} to #{output} (#{size} bytes) in #{'%.3f' % elapsed}s"
+end
+
+def cmd_resize(args)
+  input = nil
+  width = nil
+  height = nil
+  fit = nil
+  fill = nil
+  interpolation = :bilinear
+  quality = 85
+  output = nil
+
+  i = 0
+  while i < args.size
+    case args[i]
+    when "--width"
+      i += 1; width = args[i].to_i
+    when "--height"
+      i += 1; height = args[i].to_i
+    when "--fit"
+      i += 1; fit = args[i]
+    when "--fill"
+      i += 1; fill = args[i]
+    when "--interpolation"
+      i += 1
+      interpolation = args[i] == "nearest" ? :nearest : :bilinear
+    when "--quality"
+      i += 1; quality = args[i].to_i
+    when "--out"
+      i += 1; output = args[i]
+    else
+      input = args[i]
+    end
+    i += 1
+  end
+
+  unless input && output
+    $stderr.puts "Error: resize requires input file and --out"
+    usage
+  end
+
+  unless File.exist?(input)
+    $stderr.puts "Error: file not found: #{input}"
+    exit 1
+  end
+
+  start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  image = Pure::Jpeg.decode(input)
+
+  if fit
+    fw, fh = fit.split("x").map(&:to_i)
+    resized = image.resize_fit(fw, fh, interpolation: interpolation)
+  elsif fill
+    fw, fh = fill.split("x").map(&:to_i)
+    resized = image.resize_fill(fw, fh, interpolation: interpolation)
+  elsif width && height
+    resized = image.resize(width, height, interpolation: interpolation)
+  else
+    $stderr.puts "Error: specify --width/--height, --fit, or --fill"
+    usage
+  end
+
+  size = Pure::Jpeg.encode(resized, output, quality: quality)
+  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+
+  puts "Resized #{image.width}x#{image.height} -> #{resized.width}x#{resized.height} to #{output} (#{size} bytes) in #{'%.3f' % elapsed}s"
+end
+
+def cmd_benchmark(args)
+  input = args[0]
+  usage unless input
+
+  require_relative "../benchmark/decode_benchmark"
+  DecodeBenchmark.run(input)
+end
+
+case ARGV[0]
+when "decode"
+  cmd_decode(ARGV[1..])
+when "encode"
+  cmd_encode(ARGV[1..])
+when "resize"
+  cmd_resize(ARGV[1..])
+when "benchmark"
+  cmd_benchmark(ARGV[1..])
+when "version", "--version", "-v"
+  puts "pure-jpeg #{Pure::Jpeg::VERSION}"
+when nil, "help", "--help", "-h"
+  usage
+else
+  $stderr.puts "Unknown command: #{ARGV[0]}"
+  usage
+end