potracer 1.0.9 → 1.1.0

data/ext/potracer/potracer.c

@@ -6,7 +6,7 @@
 #include "potracer.h"
 
 static int
-is_colored (char *str, int row, int col, int cols, int size)
+is_colored (unsigned char *str, int row, int col, int cols, int size)
 {
   int i, start;
   unsigned char v, max, min;
@@ -36,6 +36,11 @@ params_alloc (VALUE klass)
   return Data_Wrap_Struct(klass, 0, potrace_param_free, params);
 }
 
+/**
+ * call-seq: turd_size
+ *
+ * Get the current turd size
+ */
 static VALUE
 params_get_turdsize (VALUE klass)
 {
@@ -44,6 +49,13 @@ params_get_turdsize (VALUE klass)
   return rb_int_new(params->turdsize);
 }
 
+/**
+ * call-seq: turd_size = threshold
+ *
+ * Set the turd size
+ * * +threshold+ - used to "despeckle" the bitmap to be traced, by removing all
+ *   curves whose enclosed area is below the given threshold. Default is 2.
+ */
 static VALUE
 params_set_turdsize (VALUE klass, VALUE size)
 {
@@ -53,6 +65,11 @@ params_set_turdsize (VALUE klass, VALUE size)
   return size;
 }
 
+/**
+ * call-seq: turn_policy
+ *
+ * Get the current Turnpolicy
+ */
 static VALUE
 params_get_turnpolicy (VALUE klass)
 {
@@ -61,6 +78,11 @@ params_get_turnpolicy (VALUE klass)
   return rb_int_new(params->turnpolicy);
 }
 
+/**
+ * call-seq: turn_policy = policy
+ *
+ * Set the current Turnpolicy
+ */
 static VALUE
 params_set_turnpolicy (VALUE klass, VALUE policy)
 {
@@ -70,6 +92,11 @@ params_set_turnpolicy (VALUE klass, VALUE policy)
   return policy;
 }
 
+/**
+ * call-seq: alpha_max
+ *
+ * Get the current alpha max
+ */
 static VALUE
 params_get_alphamax (VALUE klass)
 {
@@ -78,6 +105,15 @@ params_get_alphamax (VALUE klass)
   return rb_float_new(params->alphamax);
 }
 
+/**
+ * call-seq: alpha_max = max
+ *
+ * Set the alpha max
+ *
+ * * +max+ - threshold for the detection of corners. It controls the smoothness
+ *   of the traced curve, as shown in Figure 9. The current default is 1.0. The
+ *   useful range of this parameter is from 0.0 (polygon) to 1.3334 (no corners).
+ */
 static VALUE
 params_set_alphamax (VALUE klass, VALUE max)
 {
@@ -87,6 +123,11 @@ params_set_alphamax (VALUE klass, VALUE max)
   return max;
 }
 
+/**
+ * call-seq: optimized?
+ *
+ * Are curves optimized
+ */
 static VALUE
 params_get_opticurve (VALUE klass)
 {
@@ -95,6 +136,11 @@ params_get_opticurve (VALUE klass)
   return (params->opticurve == 1) ? Qtrue : Qfalse;
 }
 
+/**
+ * call-seq: optimize!
+ *
+ * Turn on curve optimization
+ */
 static VALUE
 params_set_opticurve_true (VALUE klass)
 {
@@ -104,6 +150,11 @@ params_set_opticurve_true (VALUE klass)
   return Qtrue;
 }
 
+/**
+ * call-seq: unoptimize!
+ *
+ * Turn off curve optimization
+ */
 static VALUE
 params_set_opticurve_false (VALUE klass)
 {
@@ -113,6 +164,11 @@ params_set_opticurve_false (VALUE klass)
   return Qfalse;
 }
 
+/**
+ * call-seq: tolerance
+ *
+ * Get current curve optimization tolerance
+ */
 static VALUE
 params_get_opttolerance (VALUE klass)
 {
@@ -121,6 +177,18 @@ params_get_opttolerance (VALUE klass)
   return rb_float_new(params->opttolerance);
 }
 
+/**
+ * call-seq: tolerance = amount
+ *
+ * Set current curve optimization tolerance
+ *
+ * * +amount+ - defines the amount of error allowed in curve simplification.
+ *   This value only applies if optimization is true. The current default is
+ *   0.2. Larger values tend to decrease the number of segments, at the expense
+ *   of less accuracy. The useful range is from 0 to infinity, although in
+ *   practice one would hardly choose values greater than 1 or so. For most
+ *   purposes, the default value is a good tradeoff between space and accuracy.
+ */
 static VALUE
 params_set_opttolerance (VALUE klass, VALUE tolerance)
 {
@@ -166,6 +234,27 @@ trace_trace (VALUE obj, VALUE bitmap, VALUE params)
   return obj;
 }
 
+/**
+ * call-seq: to_svg
+ *
+ * Render the traced bitmap as an SVG
+ *
+ * ==== Example
+ *
+ *  bmp = Potracer::Bitmap.new(5, 5, [
+ *    [1, 1, 1, 1, 1],
+ *    [1, 0, 0, 0, 1],
+ *    [1, 0, 0, 0, 1],
+ *    [1, 0, 0, 0, 1],
+ *    [1, 1, 1, 1, 1]
+ *  ])
+ *  params = Potracer::Params.new
+ *  trace = Potracer::Trace.new
+ *  trace.trace(bmp, params).to_svg # =>
+ *  # <svg xmlns="http://www.w3.org/2000/svg" version="1.1" width="5" height="5">
+ *  #   <path fill-rule="evenodd" fill="rgb(0,0,0)" d="M 0.000000 2.500000 C 0.000000 0.500000 0.500000 0.000000 2.500000 0.000000C 4.500000 0.000000 5.000000 0.500000 5.000000 2.500000C 5.000000 4.500000 4.500000 5.000000 2.500000 5.000000C 0.500000 5.000000 0.000000 4.500000 0.000000 2.500000M 4.000000 2.500000 C 4.000000 1.675000 3.325000 1.000000 2.500000 1.000000C 1.675000 1.000000 1.000000 1.675000 1.000000 2.500000C 1.000000 3.325000 1.675000 4.000000 2.500000 4.000000C 3.325000 4.000000 4.000000 3.325000 4.000000 2.500000" />
+ *  # </svg>"
+ */
 static VALUE
 trace_as_svg (VALUE klass)
 {
@@ -217,6 +306,28 @@ trace_as_svg (VALUE klass)
   return svg;
 }
 
+/**
+ * call-seq: to_a
+ *
+ * Convert the traced bitmap to an array in the form:
+ *
+ *   [
+ *     {:area=>25, :sign=>"+", :parts=> [
+ *       [:moveto, 0.0, 2.5],
+ *       [:curveto, 0.0, 0.5, 0.5, 0.0, 2.5, 0.0],
+ *       [:curveto, 4.5, 0.0, 5.0, 0.5, 5.0, 2.5],
+ *       [:curveto, 5.0, 4.5, 4.5, 5.0, 2.5, 5.0],
+ *       [:curveto, 0.5, 5.0, 0.0, 4.5, 0.0, 2.5]
+ *     ]},
+ *     {:area=>9, :sign=>"-", :parts=> [
+ *       [:moveto, 4.0, 2.5],
+ *       [:curveto, 4.0, 1.6749999999999998, 3.325, 1.0, 2.5, 1.0],
+ *       [:curveto, 1.6749999999999998, 1.0, 1.0, 1.6749999999999998, 1.0, 2.5],
+ *       [:curveto, 1.0, 3.325, 1.6749999999999998, 4.0, 2.5, 4.0],
+ *       [:curveto, 3.325, 4.0, 4.0, 3.325, 4.0, 2.5]
+ *     ]}
+ *   ]
+ */
 static VALUE
 trace_as_array (VALUE klass)
 {
@@ -273,16 +384,21 @@ bitmap_free (potrace_bitmap_t *bm)
   free(bm);
 }
 
-static void
-bitmap_init(int argc, VALUE *argv, VALUE klass)
-{
-  potrace_bitmap_t *bm;
-}
-
+/**
+ * call-seq: new(width=250, height=250, bits='000...', map='RGB')
+ *
+ * Creat a new Bitmap
+ *
+ * * +width+ - width of the bitmap to be traced
+ * * +height+ - height of the bitmap to be traced
+ * * +bits+ - bitmap data. Can be a multi-dimensional array or a string of pixel
+ *   data
+ * * +map+ - how pixel data is mapped if +bits+ is a string
+ */
 static VALUE
 bitmap_new (int argc, VALUE *argv, VALUE klass)
 {
-  int i, j, m, s;
+  int i, j, m;
   unsigned char *bits;
   potrace_bitmap_t *bm;
   VALUE bdata, row;
@@ -296,7 +412,7 @@ bitmap_new (int argc, VALUE *argv, VALUE klass)
 
   if (argc > 2) {
     if (T_STRING == TYPE(argv[2])) {
-      bits = StringValuePtr(argv[2]);
+      bits = (unsigned char *)StringValuePtr(argv[2]);
       m = strlen(StringValuePtr(argv[3]));
       for (i = 0; i < bm->h; i++) {
         for (j = 0; j < bm->w; j++) {
@@ -316,6 +432,11 @@ bitmap_new (int argc, VALUE *argv, VALUE klass)
   return bdata;
 }
 
+/**
+ * call-seq: width
+ *
+ * Get the width in pixels
+ */
 static VALUE
 bitmap_get_width (VALUE klass)
 {
@@ -324,6 +445,11 @@ bitmap_get_width (VALUE klass)
   return rb_int_new(bm->w);
 }
 
+/**
+ * call-seq: height
+ *
+ * Get the height in pixels
+ */
 static VALUE
 bitmap_get_height (VALUE klass)
 {
@@ -332,6 +458,11 @@ bitmap_get_height (VALUE klass)
   return rb_int_new(bm->h);
 }
 
+/**
+ * call-seq: to_a
+ *
+ * Retrieve the bitmap data as a multi-dimensional array of 1s and 0s
+ */
 static VALUE
 bitmap_as_array (VALUE klass)
 {
@@ -353,8 +484,12 @@ bitmap_as_array (VALUE klass)
 
 void
 Init_potracer () {
-  // Define the Potracer module
+  /**
+   * Define-module: Potracer
+   * A home for all things Potrace
+   */
   rb_mPotracer = rb_define_module("Potracer");
+  /* VERSION: Version of Potrace */
   rb_define_const(rb_mPotracer, "VERSION", rb_str_new2(potrace_version()));
 
   // Define the Trace class inside the Potracer module
@@ -364,7 +499,11 @@ Init_potracer () {
   rb_define_method(rb_cPotracerTrace, "to_a", trace_as_array, 0);
   rb_define_method(rb_cPotracerTrace, "to_svg", trace_as_svg, 0);
 
-  // Define the Params class inside the Potracer module
+  /**
+   * Document-class: Potracer::Params
+   *
+   * Params define how the Bitmap is traced
+   */
   rb_cPotracerParams = rb_define_class_under(rb_mPotracer, "Params", rb_cObject);
   rb_define_alloc_func(rb_cPotracerParams, params_alloc);
   rb_define_method(rb_cPotracerParams, "turd_size", params_get_turdsize, 0);
@@ -379,7 +518,41 @@ Init_potracer () {
   rb_define_method(rb_cPotracerParams, "tolerance", params_get_opttolerance, 0);
   rb_define_method(rb_cPotracerParams, "tolerance=", params_set_opttolerance, 1);
 
-  // Define the Turnpolicy module inside the Potracer module
+  /**
+   * Document-const: BLACK
+   *  prefers to connect black (foreground) components
+   */
+  /**
+   * Document-const: WHITE
+   *  prefers to connect white (background) components
+   */
+  /**
+   * Document-const: LEFT
+   *  always take a left turn
+   */
+  /**
+   * Document-const: RIGHT
+   *  always take a right turn
+   */
+  /**
+   * Document-const: MINORITY
+   *  prefers to connect the color (black or white) that occurs least
+   *  frequently in a local neighborhood of the current position
+   */
+  /**
+   * Document-const: MAJORITY
+   *  prefers to connect the color (black or white) that occurs most
+   *  frequently in a local neighborhood of the current position
+   */
+  /**
+   * Document-const: RANDOM
+   *  choose pseudo-ramdomly
+   */
+  /**
+   * Document-class: Potracer::Turnpolicy
+   *  The Turnpolicy determines how to resolve ambiguities during decomposition
+   *  of bitmaps into paths.
+   */
   rb_mTurnpolicy = rb_define_module_under(rb_mPotracer, "Turnpolicy");
   rb_define_const(rb_mTurnpolicy, "BLACK", rb_int_new(POTRACE_TURNPOLICY_BLACK));
   rb_define_const(rb_mTurnpolicy, "WHITE", rb_int_new(POTRACE_TURNPOLICY_WHITE));
@@ -389,7 +562,10 @@ Init_potracer () {
   rb_define_const(rb_mTurnpolicy, "MAJORITY", rb_int_new(POTRACE_TURNPOLICY_MAJORITY));
   rb_define_const(rb_mTurnpolicy, "RANDOM", rb_int_new(POTRACE_TURNPOLICY_RANDOM));
 
-  // Define the Bitmap class inside the Potracer module
+  /**
+   * Document-class: Potracer::Bitmap
+   *   The Bitmap is Potracer's representation of a bitmap in memory
+   */
   rb_cPotracerBitmap = rb_define_class_under(rb_mPotracer, "Bitmap", rb_cObject);
   rb_define_singleton_method(rb_cPotracerBitmap, "new", bitmap_new, -1);
   rb_define_method(rb_cPotracerBitmap, "width", bitmap_get_width, 0);

data/lib/potracer.rb

@@ -1,7 +1,27 @@
-require_relative 'potracer/potracer'
+begin
+  require_relative '../build/potracer'
+rescue LoadError
+  require_relative '../ext/potracer/potracer'
+end
 
 module Potracer
+
+  ##
+  # This class represents a trace of a Potracer::Bitmap
+
   class Trace
+
+    ##
+    # Trace the given +bitmap+
+    #
+    # ==== Attributes
+    #
+    # * +bitmap+ - an instance of Potracer::Bitmap. If not given the +@bitmap+
+    #   is used.
+    # * +params+ - an instance of Potracer::Params. If not given +@params+ is
+    #   used.
+    # * +block+ - optional block called to report trace progress
+
     def trace(bitmap=nil, params=nil, &block)
       if block_given?
         self.do_trace(bitmap || @bitmap, params || @params, &block)
@@ -10,6 +30,28 @@ module Potracer
       end
     end
 
+    ##
+    # Trace a bitmap
+    #
+    # ==== Attributes
+    #
+    # * +bmp+ - mapped to a Potracer::Bitmap either a multi-dimensional array of
+    #   bits or a string of image data
+    # * +width+ - width of the image to be mapped if +bmp+ is a string
+    # * +height+ - height of the image to be mapped if +bmp+ is a string
+    # * +map+ - pixel data format if +bmp+ is a string
+    # * +block+ - optional block called to report trace progress
+    #
+    # ==== Example
+    #
+    #   require 'ruby-progressbar'
+    #
+    #   pbar = ProgressBar.create(title: 'Tracing')
+    #   Potracer::Trace.bitmap(bits) do |percent|
+    #     pbar.progress = percent
+    #   end
+    #   pbar.finish
+
     def self.bitmap(bmp, width=nil, height=nil, map='RGB', &block)
       width ||= bmp.map {|r| r.length}.max
       height ||= bmp.length

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: potracer
 version: !ruby/object:Gem::Version
-  version: 1.0.9
+  version: 1.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-22 00:00:00.000000000 Z
+date: 2013-03-10 00:00:00.000000000 Z
 dependencies: []
 description: Ruby bindings for the potrace library.
 email: k.parnell@gmail.com