autotrace 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dce37787636a8564e56fc6694fea1bbc27b2a484ff3f1ae0bf6bba498e1e76e0
+  data.tar.gz: dce6102e09ddcfa1f46187a8935b118ea9a2094cbfbb1f7375caebe2fc14b349
+SHA512:
+  metadata.gz: b78ce717031ce4189cfd0ad409f948da4be9747d53d585b8c0726fa81d300d0fbd1493b2ed65e210b4a2cee1e91bc3977449bd4306fc0e0833c270f64cc6ed5a
+  data.tar.gz: 83553a622e9900f3ad94b5d0594a7763a3c5278619c126d13d45680deeea04390a91bafe258f452f38cf3ebd1737c45b50e32fab88aeb935094f9a69e722ffde

data/.rubocop.yml

@@ -0,0 +1,29 @@
+AllCops:
+  TargetRubyVersion: 3.0
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+3.3.5

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-04-10
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dylan Player
+
+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,238 @@
+# 🎨 Autotrace
+
+Ruby bindings for the Autotrace library, which converts raster images (like PNG) into vector graphics (like SVG). This gem provides a Ruby interface to the powerful Autotrace library, allowing for easy conversion of bitmap images to vector formats with extensive configuration options.
+
+## 📦 Installation
+
+### Prerequisites
+
+Before installing the gem, you need to install the Autotrace library and its dependencies on your system.
+
+#### 🍎 macOS
+
+```bash
+brew install libffi
+brew install autotrace
+```
+
+#### 🐧 Ubuntu
+
+Since Autotrace is not available in the default Ubuntu repositories, you'll need to compile it from source:
+
+```bash
+# Install dependencies
+sudo apt update
+sudo apt install -y \
+  build-essential \
+  git \
+  libmagickcore-dev \
+  autotools-dev \
+  autopoint \
+  diffutils \
+  libtool \
+  intltool \
+  libpng-dev \
+  libexif-dev \
+  libtiff5-dev \
+  libjpeg-dev \
+  libxml2-dev \
+  libbz2-dev \
+  libpstoedit-dev \
+  libfreetype6-dev \
+  libpstoedit0c2a \
+  libbz2-1.0 \
+  libgd3 \
+  libffi-dev \
+  pkg-config
+
+# Clone the repository
+git clone https://github.com/autotrace/autotrace.git
+cd autotrace
+
+# Generate configuration files
+./autogen.sh
+
+# Configure and build
+./configure --prefix=/usr
+make
+
+# Test if it works before installing
+./autotrace --version
+
+# Install and update the shared library cache
+sudo make install
+sudo ldconfig
+```
+
+**Note:** If you encounter issues with ImageMagick or Pstoedit during compilation, you can disable them with configuration options:
+
+- `./configure --without-magick` - Disable ImageMagick support
+- `./configure --without-pstoedit` - Disable Pstoedit support
+
+For more detailed installation instructions and troubleshooting, refer to the [official Autotrace installation guide](https://github.com/autotrace/autotrace/blob/master/INSTALL.md).
+
+#### 🐳 Using Docker
+
+There is a reference Dockerfile here: [examples/Dockerfile](examples/Dockerfile).
+
+```bash
+# Build the Docker image
+docker build -t autotrace-example -f examples/Dockerfile .
+
+# Create a directory to store output files
+mkdir -p output
+
+# Run the container with your image
+docker run -v /path/to/your/image.png:/app/sample.png -v $(pwd)/output:/app/output autotrace-example
+```
+
+### 💎 Installing the Gem
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'autotrace'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install autotrace
+```
+
+## 🚀 Usage
+
+### Basic Usage
+
+Convert a PNG image to SVG:
+
+```ruby
+require 'autotrace'
+
+# Convert image.png to image.svg
+Autotrace.trace_image('image.png', output_suffix: 'svg')
+```
+
+### Advanced Usage
+
+The library provides extensive configuration options for controlling the tracing process:
+
+```ruby
+require 'autotrace'
+
+# Convert with custom options
+Autotrace.trace_image('input.png',
+  output_suffix: 'svg',
+  background_color: 'FFFFFF',  # White background
+  error_threshold: 1.0,        # Lower error threshold for more detail
+  despeckle_level: 2,          # Remove small artifacts
+  preserve_width: true,        # Preserve line widths
+  centerline: false,           # Don't trace along centerline
+  noise_removal: 0.95,         # Remove noise while preserving detail
+  color_count: 8              # Limit to 8 colors
+)
+```
+
+### ⚙️ Available Options
+
+The following options are available for fine-tuning the conversion process:
+
+- `background_color`: Background color in hex format (e.g. "FFFFFF")
+- `centerline`: Whether to trace along the centerline (boolean)
+- `charcode`: Character code for text output (integer)
+- `color_count`: Number of colors to use (integer)
+- `corner_always_threshold`: Threshold for corner detection (float)
+- `corner_surround`: Number of points to consider for corner detection (integer)
+- `corner_threshold`: Threshold for corner detection (float)
+- `despeckle_level`: Level of despeckling to apply (integer)
+- `despeckle_tightness`: Tightness of despeckling (float)
+- `dpi`: DPI setting for output (affects MIF output scaling) (integer)
+- `error_threshold`: Error threshold for curve fitting (float)
+- `filter_iterations`: Number of filter iterations (integer)
+- `line_reversion_threshold`: Threshold for line reversion (float)
+- `line_threshold`: Threshold for line detection (float)
+- `noise_removal`: Level of noise removal (float)
+- `preserve_width`: Whether to preserve line width (boolean)
+- `remove_adjacent_corners`: Whether to remove adjacent corners (boolean)
+- `tangent_surround`: Number of points to consider for tangent detection (integer)
+- `width_weight_factor`: Weight factor for width preservation (float)
+
+## 🔧 Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+### 🚀 Creating a Release
+
+This project uses GitHub Actions to automate the release process. To create a new release:
+
+1. Update the version number in `lib/autotrace/version.rb`
+2. Update the `CHANGELOG.md` with the changes for the new version
+3. Commit your changes:
+   ```bash
+   git add lib/autotrace/version.rb CHANGELOG.md
+   git commit -m "Bump version to vX.Y.Z"
+   ```
+4. Create and push a new tag:
+   ```bash
+   git tag -a vX.Y.Z -m "Release vX.Y.Z"
+   git push origin vX.Y.Z
+   ```
+
+The GitHub Actions workflow will automatically:
+
+- Run the test suite
+- Build the gem
+- Publish the gem to RubyGems.org
+
+**Note:** Make sure you have set up the `RUBYGEMS_API_KEY` secret in your GitHub repository settings before creating a release. You can generate an API key from your RubyGems account settings.
+
+## 🧪 Testing
+
+The gem includes a test suite that verifies the basic functionality works correctly.
+
+### Prerequisites for Testing
+
+1. Make sure you have the Autotrace C library installed (see Installation section above)
+2. Place a test image named `tower.png` in the `test/files` directory
+
+### Running the Tests
+
+You can run the tests with:
+
+```bash
+# Run all tests
+rake test
+
+# Run a specific test file
+ruby -I lib:test test/test_autotrace.rb
+```
+
+The test suite includes a basic test that converts a PNG image to SVG format to ensure the gem is working correctly with your system's Autotrace installation.
+
+### Troubleshooting Tests
+
+If you encounter errors during testing:
+
+1. Verify that Autotrace is correctly installed on your system by running `autotrace --version` in your terminal
+2. Check that the test image file exists at `test/files/tower.png`
+3. Look for any warning messages about unsupported or missing libraries
+
+## 🤝 Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/851-labs/autotrace. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/851-labs/autotrace/blob/main/CODE_OF_CONDUCT.md).
+
+## 📄 License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## ✨ Code of Conduct
+
+Everyone interacting in the Autotrace project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/851-labs/autotrace/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/examples/Dockerfile

@@ -0,0 +1,93 @@
+FROM ruby:3.3.5-slim
+
+# Install dependencies for Autotrace based on official build script
+RUN apt-get update && apt-get install -y \
+  build-essential \
+  git \
+  libmagickcore-dev \
+  autotools-dev \
+  autopoint \
+  diffutils \
+  libtool \
+  intltool \
+  libpng-dev \
+  libexif-dev \
+  libtiff5-dev \
+  libjpeg-dev \
+  libxml2-dev \
+  libbz2-dev \
+  libpstoedit-dev \
+  libfreetype6-dev \
+  libpstoedit0c2a \
+  libbz2-1.0 \
+  libgd3 \
+  libffi-dev \
+  pkg-config \
+  curl \
+  wget \
+  && rm -rf /var/lib/apt/lists/*
+
+# Clone and build Autotrace
+WORKDIR /tmp
+RUN git clone https://github.com/autotrace/autotrace.git && \
+  cd autotrace && \
+  ./autogen.sh && \
+  ./configure --prefix=/usr && \
+  make && \
+  make install && \
+  ldconfig && \
+  cd .. && \
+  rm -rf autotrace
+
+# Set up working directory for the application
+WORKDIR /app
+
+# Create output directory
+RUN mkdir -p /app/output
+
+# Copy the entire gem source code to the container
+COPY . /app/autotrace-gem/
+
+# Install required dependencies for the gem
+RUN gem install ffi -v "~> 1.17.1"
+
+# Copy the example files to /app
+COPY examples/trace_example.rb /app/trace_example.rb
+COPY examples/run.sh /app/run.sh
+
+# Make the run script executable
+RUN chmod +x /app/run.sh
+
+# Set RUBYLIB environment variable to include the autotrace gem lib directory
+ENV RUBYLIB="/app/autotrace-gem/lib:${RUBYLIB}"
+
+# Print information about the available libraries
+RUN ldconfig -p | grep "libgobject\\|libglib\\|libMagickCore\\|libpstoedit\\|libpng"
+
+# Set working directory back to /app
+WORKDIR /app
+
+# Find the locations of the required libraries for debugging
+RUN echo "Checking for required libraries:" && \
+  find /usr/lib -name "libautotrace*" && \
+  find /usr/local/lib -name "libautotrace*" && \
+  ldconfig -p | grep autotrace
+
+# Verify that we can load the autotrace gem with better error handling
+RUN ruby -e "begin; \
+  require 'autotrace'; \
+  puts 'Autotrace gem loaded successfully!'; \
+  rescue LoadError => e; \
+  puts \"LoadError: #{e.message}\"; \
+  exit 1; \
+  rescue => e; \
+  puts \"Error: #{e.class.name} - #{e.message}\"; \
+  puts e.backtrace; \
+  exit 1; \
+  end"
+
+# Set the entry point to the shell script
+ENTRYPOINT ["/app/run.sh"]
+
+# The sample.png should be mounted from the host
+# Example: docker run -v $(pwd)/examples/sample.png:/app/sample.png -v $(pwd)/output:/app/output autotrace-example

data/examples/README.md

@@ -0,0 +1,62 @@
+# Autotrace Examples
+
+This directory contains examples demonstrating how to use the Autotrace gem.
+
+## Contents
+
+- `Dockerfile` - Docker setup for running Autotrace
+- `trace_example.rb` - Example Ruby script showing various tracing options
+- `sample.png` - Sample image for the examples
+
+## Running with Docker
+
+The provided Dockerfile sets up a complete environment for running Autotrace.
+
+### Build the Docker image
+
+```bash
+docker build -t autotrace-example -f examples/Dockerfile .
+```
+
+### Run the container with the sample image
+
+```bash
+# Create a directory to store output files
+mkdir -p output
+
+# Run the container with the sample image mounted
+docker run -v $(pwd)/examples/sample.png:/app/sample.png -v $(pwd)/output:/app/output autotrace-example
+```
+
+### Using your own images
+
+You can convert your own images by mounting them to the container:
+
+```bash
+docker run -v /path/to/your/image.png:/app/sample.png -v $(pwd)/output:/app/output autotrace-example
+```
+
+## Running the Ruby Example Directly
+
+If you have Autotrace installed on your system, you can run the example script directly:
+
+```bash
+cd examples
+ruby trace_example.rb
+```
+
+Make sure you have the `sample.png` file in the same directory as the script.
+
+## Output
+
+The traced vector files will be created in the same directory as the input file, with the appropriate extension:
+
+- `sample.svg` - SVG vector output
+- `sample.eps` - EPS vector output (if you run Example 3)
+
+## Additional Resources
+
+For more information about Autotrace and its options, see:
+
+- [Autotrace GitHub Repository](https://github.com/autotrace/autotrace)
+- [Ruby Gem Documentation](https://github.com/851-labs/autotrace)

data/examples/run.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+
+echo "==================================================="
+echo "Autotrace - Converting raster images to vector graphics"
+echo "==================================================="
+
+if [ ! -f /app/sample.png ]; then
+  echo "Error: sample.png not found in /app directory."
+  echo "Please mount your image to /app/sample.png:"
+  echo "  docker run -v /path/to/your/image.png:/app/sample.png autotrace-example"
+  exit 1
+fi
+
+echo "Found image: /app/sample.png"
+echo "Running trace script..."
+echo "==================================================="
+
+# Run the Ruby example script
+ruby /app/trace_example.rb
+
+# Copy output files to output directory
+cp /app/*.svg /app/output/ 2>/dev/null || true
+cp /app/*.eps /app/output/ 2>/dev/null || true
+
+echo "==================================================="
+echo "Process complete!"
+echo "Output files can be found in the mounted output directory"
+echo "===================================================" 

data/examples/trace_example.rb

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+puts "Ruby Version: #{RUBY_VERSION}"
+puts "Load Path: #{$LOAD_PATH.join(":")}"
+puts "Current Directory: #{Dir.pwd}"
+puts "Files in /app/autotrace-gem/lib: #{Dir.glob("/app/autotrace-gem/lib/**/*")}"
+
+begin
+  puts "Attempting to require autotrace..."
+  require "autotrace"
+  puts "Successfully loaded autotrace!"
+rescue LoadError => e
+  puts "Error loading autotrace: #{e.message}"
+  puts "Try loading from direct path..."
+  require_relative "/app/autotrace-gem/lib/autotrace"
+  puts "Successfully loaded autotrace from direct path!"
+end
+
+# This example demonstrates how to use the Autotrace gem to convert
+# a raster image to a vector format with various options.
+
+def trace_with_options(input_file, options = {})
+  puts "Converting #{input_file} with options: #{options.inspect}"
+
+  # Trace the image with the specified options
+  result = Autotrace.trace_image(
+    input_file,
+    **options
+  )
+
+  puts "Conversion complete! Output file: #{result.path}"
+
+  # Return the result file
+  result
+end
+
+# Example 1: Simple conversion to SVG
+puts "Example 1: Simple conversion to SVG"
+trace_with_options("sample.png", output_suffix: "svg")
+
+# Example 2: Conversion with custom options
+puts "\nExample 2: Conversion with custom options"
+trace_with_options("sample.png",
+                   output_suffix: "svg",
+                   background_color: "FFFFFF",  # White background
+                   error_threshold: 1.0,        # Lower error threshold for more detail
+                   despeckle_level: 2,          # Remove small artifacts
+                   preserve_width: true,        # Preserve line widths
+                   centerline: false,           # Don't trace along centerline
+                   noise_removal: 0.95) # Remove noise while preserving detail
+
+# Example 3: Convert to EPS format
+puts "\nExample 3: Convert to EPS format"
+trace_with_options("sample.png", output_suffix: "eps")
+
+puts "\nAll conversions completed successfully!"

data/lib/autotrace/ffi.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module Autotrace
+  # FFI module that provides bindings to the Autotrace C library.
+  # This module handles all the low-level interactions with the C library
+  # through FFI (Foreign Function Interface).
+  module FFI
+    extend ::FFI::Library
+
+    ffi_lib_flags :now, :global
+
+    ffi_lib [
+      # libgobject (Linux, macOS, Windows)
+      "libgobject-2.0", # generic name (might work if found via linker)
+      "libgobject-2.0.so.0",       # typical on Linux distributions (Debian/RedHat)
+      "libgobject-2.0.dylib",      # common on macOS (if installed via Homebrew or MacPorts)
+      "gobject-2.0.dll" # common on Windows
+    ]
+
+    ffi_lib [
+      # libglib
+      "libglib-2.0",
+      "libglib-2.0.so.0",
+      "libglib-2.0.dylib",
+      "glib-2.0.dll"
+    ]
+
+    ffi_lib [
+      # ImageMagick's MagickCore library
+      "libMagickCore-7.Q16HDRI",
+      "libMagickCore-6.Q16HDRI",
+      "libMagickCore-7.Q16.so",
+      "libMagickCore-6.Q16.so.6",
+      "libMagickCore-6.Q16.so"
+    ]
+
+    ffi_lib [
+      # pstoedit library
+      "libpstoedit",
+      "libpstoedit.so.0",
+      "libpstoedit.dylib",
+      "pstoedit.dll"
+    ]
+
+    ffi_lib [
+      # libpng library
+      "libpng",
+      "libpng16.so.16", # Often libpng is packaged as libpng16 on newer systems
+      "libpng.dylib",
+      "png.dll"
+    ]
+
+    # Load the main Autotrace library with alternate names:
+    ffi_lib [
+      "libautotrace.3",
+      "libautotrace.so.3",  # Linux typical shared object name
+      "libautotrace.dylib", # macOS typical dynamic library name
+      "autotrace.dll"       # Windows DLL alternative
+    ]
+
+    # Module providing bindings to standard C library functions
+    module CStdLib
+      extend ::FFI::Library
+      ffi_lib ::FFI::Library::LIBC
+
+      attach_function :fopen, %i[string string], :pointer
+      attach_function :fclose, [:pointer], :int
+    end
+
+    # Structure representing an RGB color in the Autotrace library
+    class AtColor < ::FFI::Struct
+      layout :r, :uint8, :g, :uint8, :b, :uint8
+    end
+
+    # Structure containing all the fitting options for the Autotrace algorithm
+    class AtFittingOpts < ::FFI::Struct
+      layout :background_color,         :pointer, # at_color*
+             :charcode,                 :uint,
+             :color_count,              :uint,
+             :corner_always_threshold,  :float,
+             :corner_surround,          :uint,
+             :corner_threshold,         :float,
+             :error_threshold,          :float,
+             :filter_iterations,        :uint,
+             :line_reversion_threshold, :float,
+             :line_threshold,           :float,
+             :remove_adjacent_corners,  :bool,
+             :tangent_surround,         :uint,
+             :despeckle_level,          :uint,
+             :despeckle_tightness,      :float,
+             :noise_removal,            :float,
+             :centerline,               :bool,
+             :preserve_width,           :bool,
+             :width_weight_factor,      :float
+    end
+
+    # Structure containing output options for the Autotrace library
+    class AtOutputOpts < ::FFI::Struct
+      layout :dpi, :int
+    end
+
+    # Initialize the Autotrace library
+    attach_function :autotrace_init, [], :void
+    # Initialize input handlers
+    attach_function :at_input_init, [], :int
+    # Initialize modules
+    attach_function :at_module_init, [], :int
+
+    # Create and free fitting options
+    attach_function :at_fitting_opts_new, [], :pointer
+    attach_function :at_fitting_opts_free, [:pointer], :void
+
+    # Create and free output options
+    attach_function :at_output_opts_new, [], :pointer
+    attach_function :at_output_opts_free, [:pointer], :void
+
+    # Get input handler for a specific file
+    attach_function :at_input_get_handler, [:string], :pointer
+    # Read bitmap from file
+    attach_function :at_bitmap_read, %i[pointer string pointer pointer pointer], :pointer
+
+    # Create splines from bitmap
+    attach_function :at_splines_new, %i[pointer pointer pointer pointer], :pointer
+    # Write splines to output file
+    attach_function :at_splines_write, %i[pointer pointer string pointer pointer pointer pointer], :void
+
+    # Get output handler by file suffix
+    attach_function :at_output_get_handler_by_suffix, [:string], :pointer
+
+    # Free allocated memory
+    attach_function :at_bitmap_free, [:pointer], :void
+    attach_function :at_splines_free, [:pointer], :void
+  end
+end

data/lib/autotrace/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Autotrace
+  VERSION = "0.1.0"
+end

data/lib/autotrace.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require_relative "autotrace/version"
+require_relative "autotrace/ffi"
+
+# Autotrace is a Ruby gem that provides bindings to the Autotrace library,
+# which converts raster images (like PNG) into vector graphics (like SVG).
+#
+# The library supports various input and output formats, and provides extensive
+# configuration options for controlling the tracing process.
+#
+# @example Converting a PNG to SVG
+#   Autotrace.trace_image("input.png", output_suffix: "svg")
+#
+# @example Converting with custom options
+#   Autotrace.trace_image("input.png",
+#     output_suffix: "svg",
+#     background_color: "FFFFFF",
+#     error_threshold: 1.0
+#   )
+module Autotrace
+  # Base error class for all Autotrace-related errors
+  class Error < StandardError; end
+
+  class << self
+    attr_accessor :initialized
+
+    # Initialize the Autotrace library. This must be called before any other
+    # operations. It sets up input handlers and other necessary components.
+    #
+    # @return [void]
+    def init_autotrace
+      return if initialized
+
+      FFI.autotrace_init
+      FFI.at_input_init
+      FFI.at_module_init
+
+      self.initialized = true
+    end
+
+    # Convert a raster image to a vector graphic format.
+    #
+    # @param input_image [String] Path to the input raster image
+    #
+    # @param output_suffix [String] Desired output format (e.g. "svg", "eps")
+    # @param output_file [String, nil] Path to write the output file. If nil,
+    #   the output file will be "<basename>.<output_suffix>" in the same folder
+    #   as the input file.
+    #
+    # @param background_color [String, nil] Background color in hex format (e.g. "FFFFFF")
+    # @param centerline [Boolean] Whether to trace along the centerline
+    # @param charcode [Integer] Character code for text output
+    # @param color_count [Integer] Number of colors to use
+    # @param corner_always_threshold [Float] Threshold for corner detection
+    # @param corner_surround [Integer] Number of points to consider for corner detection
+    # @param corner_threshold [Float] Threshold for corner detection
+    # @param despeckle_level [Integer] Level of despeckling to apply
+    # @param despeckle_tightness [Float] Tightness of despeckling
+    # @param dpi [Integer] DPI setting for output (affects MIF output scaling)
+    # @param error_threshold [Float] Error threshold for curve fitting
+    # @param filter_iterations [Integer] Number of filter iterations
+    # @param line_reversion_threshold [Float] Threshold for line reversion
+    # @param line_threshold [Float] Threshold for line detection
+    # @param noise_removal [Float] Level of noise removal
+    # @param preserve_width [Boolean] Whether to preserve line width
+    # @param remove_adjacent_corners [Boolean] Whether to remove adjacent corners
+    # @param tangent_surround [Integer] Number of points to consider for tangent detection
+    # @param width_weight_factor [Float] Weight factor for width preservation
+    #
+    # @return [File] A File object pointing to the newly created vector file
+    # @raise [Error] If any step in the conversion process fails
+    def trace_image(
+      input_image,
+      output_suffix: "svg",
+      output_file: nil,
+      background_color: nil,
+      centerline: false,
+      charcode: 0,
+      color_count: 0,
+      corner_always_threshold: 60.0,
+      corner_surround: 4,
+      corner_threshold: 100.0,
+      despeckle_level: 0,
+      despeckle_tightness: 2.0,
+      dpi: 0,
+      error_threshold: 2.0,
+      filter_iterations: 4,
+      line_reversion_threshold: 0.01,
+      line_threshold: 1.0,
+      noise_removal: 0.99,
+      preserve_width: false,
+      remove_adjacent_corners: false,
+      tangent_surround: 3,
+      width_weight_factor: 0.0
+    )
+      init_autotrace
+
+      # 1. Create the input & output option structs
+      fitting_opts_ptr = FFI.at_fitting_opts_new
+      raise Error, "Failed to allocate fitting options" if fitting_opts_ptr.null?
+
+      output_opts_ptr = FFI.at_output_opts_new
+      raise Error, "Failed to allocate output options" if output_opts_ptr.null?
+
+      # 2. Fill in all the fields from your arguments.
+      configure_fitting_opts(
+        fitting_opts_ptr,
+        background_color: background_color,
+        centerline: centerline,
+        charcode: charcode,
+        color_count: color_count,
+        corner_always_threshold: corner_always_threshold,
+        corner_surround: corner_surround,
+        corner_threshold: corner_threshold,
+        despeckle_level: despeckle_level,
+        despeckle_tightness: despeckle_tightness,
+        error_threshold: error_threshold,
+        filter_iterations: filter_iterations,
+        line_reversion_threshold: line_reversion_threshold,
+        line_threshold: line_threshold,
+        noise_removal: noise_removal,
+        preserve_width: preserve_width,
+        remove_adjacent_corners: remove_adjacent_corners,
+        tangent_surround: tangent_surround,
+        width_weight_factor: width_weight_factor
+      )
+
+      configure_output_opts(output_opts_ptr, dpi: dpi)
+
+      # 3. Acquire input handler & read the bitmap
+      input_handler = FFI.at_input_get_handler(input_image)
+      raise Error, "Failed to get input handler for #{input_image}" if input_handler.null?
+
+      bitmap = FFI.at_bitmap_read(input_handler, input_image, nil, nil, nil)
+      raise Error, "Failed to read bitmap from #{input_image}" if bitmap.null?
+
+      # 4. Create splines
+      splines = FFI.at_splines_new(bitmap, fitting_opts_ptr, nil, nil)
+      raise Error, "Failed to create splines" if splines.null?
+
+      # 5. Output handler
+      output_handler = FFI.at_output_get_handler_by_suffix(output_suffix)
+      raise Error, "Unknown output format: .#{output_suffix}" if output_handler.null?
+
+      # 6. Determine output file path
+      if output_file.nil? || output_file.empty?
+        # default to "<basename>.<suffix>"
+        output_basename = File.basename(input_image, ".*")
+        output_file = "#{output_basename}.#{output_suffix}"
+      end
+
+      # 7. Write to a real file
+      c_file = FFI::CStdLib.fopen(output_file, "wb")
+      raise Error, "Failed to open #{output_file} with C fopen" if c_file.null?
+
+      FFI.at_splines_write(
+        output_handler,
+        c_file,
+        output_file,
+        output_opts_ptr,
+        splines,
+        nil, # msg_func
+        nil  # msg_data
+      )
+
+      # Close
+      FFI::CStdLib.fclose(c_file)
+
+      # (Optional) free memory
+      FFI.at_fitting_opts_free(fitting_opts_ptr)
+      FFI.at_output_opts_free(output_opts_ptr)
+      FFI.at_bitmap_free(bitmap)
+      FFI.at_splines_free(splines)
+
+      File.open(output_file, "rb")
+    end
+
+    private
+
+    # Convert a background color hex string (e.g. "FF00FF") into an at_color struct pointer
+    # or return nil if background_color is not specified.
+    def parse_background_color(background_color)
+      return nil if background_color.nil? || background_color.empty?
+
+      # Convert e.g. "FFFFFF" => r=255,g=255,b=255
+      rgb = background_color.strip
+      rgb = rgb.delete_prefix("#") # remove leading '#' if present
+      raise Error, "Background color must be 6 hex digits" unless rgb.size == 6
+
+      r = rgb[0..1].to_i(16)
+      g = rgb[2..3].to_i(16)
+      b = rgb[4..5].to_i(16)
+
+      # Allocate an AtColor struct in memory
+      color_ptr = ::FFI::MemoryPointer.new(:uint8, 3)
+      color_struct = FFI::AtColor.new(color_ptr)
+      color_struct[:r] = r
+      color_struct[:g] = g
+      color_struct[:b] = b
+      color_ptr
+    end
+
+    # Fill in at_fitting_opts_type
+    def configure_fitting_opts(
+      fitting_opts_ptr,
+      background_color: nil,
+      centerline: false,
+      charcode: 0,
+      color_count: 0,
+      corner_always_threshold: 60.0,
+      corner_surround: 4,
+      corner_threshold: 100.0,
+      despeckle_level: 0,
+      despeckle_tightness: 2.0,
+      error_threshold: 2.0,
+      filter_iterations: 4,
+      line_reversion_threshold: 0.01,
+      line_threshold: 1.0,
+      noise_removal: 0.99,
+      preserve_width: false,
+      remove_adjacent_corners: false,
+      tangent_surround: 3,
+      width_weight_factor: 0.0
+    )
+      opts = FFI::AtFittingOpts.new(fitting_opts_ptr)
+
+      # Possibly parse background color
+      bg_ptr = parse_background_color(background_color)
+      opts[:background_color]          = bg_ptr
+      opts[:charcode]                  = charcode
+      opts[:color_count]               = color_count
+      opts[:corner_always_threshold]   = corner_always_threshold
+      opts[:corner_surround]           = corner_surround
+      opts[:corner_threshold]          = corner_threshold
+      opts[:despeckle_level]           = despeckle_level
+      opts[:despeckle_tightness]       = despeckle_tightness
+      opts[:error_threshold]           = error_threshold
+      opts[:filter_iterations]         = filter_iterations
+      opts[:line_reversion_threshold]  = line_reversion_threshold
+      opts[:line_threshold]            = line_threshold
+      opts[:noise_removal]             = noise_removal
+      opts[:preserve_width]            = preserve_width
+      opts[:remove_adjacent_corners]   = remove_adjacent_corners
+      opts[:tangent_surround]          = tangent_surround
+      opts[:width_weight_factor]       = width_weight_factor
+      opts[:centerline]                = centerline
+
+      fitting_opts_ptr
+    end
+
+    # Fill in at_output_opts_type (currently only 'dpi')
+    def configure_output_opts(output_opts_ptr, dpi: 0)
+      out = FFI::AtOutputOpts.new(output_opts_ptr)
+      out[:dpi] = dpi
+      output_opts_ptr
+    end
+  end
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: autotrace
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dylan Player
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-04-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.17.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.17.1
+description: |
+  Ruby bindings for the Autotrace library, which converts raster images (like PNG)
+  into vector graphics (like SVG). This gem provides a Ruby interface to the
+  powerful Autotrace library, allowing for easy conversion of bitmap images to
+  vector formats with extensive configuration options.
+email:
+- dylan@851.sh
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- ".ruby-version"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- examples/Dockerfile
+- examples/README.md
+- examples/run.sh
+- examples/sample.png
+- examples/trace_example.rb
+- lib/autotrace.rb
+- lib/autotrace/ffi.rb
+- lib/autotrace/version.rb
+homepage: https://github.com/851-labs/autotrace
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/851-labs/autotrace
+  source_code_uri: https://github.com/851-labs/autotrace
+  changelog_uri: https://github.com/851-labs/autotrace/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: Ruby bindings for the Autotrace library
+test_files: []