NAME
    Image::Embroidery - Parse and display embroidery data files

SYNOPSIS
      use Image::Embroidery;

      # Constructor
      $emb = Image::Embroidery->new();

ABSTRACT
    Parse and display embroidery data files

DESCRIPTION
    This module can be used to read, write and (with GD) display embroidery
    data files. It currently only supports Tajima DST files, but if there is
    any interest it could be expanded to deal with other formats. In its
    current form it isn't ideal for creating or modifying patterns, but I'm
    reluctant to put much effort into it until someone tells me they are
    using it.

EXAMPLES
    This is an example of using the module to manipulate a data file and
    write out the changes.

        use Image::Embroidery qw(:all);

        $emb = Image::Embroidery->new();

        $emb->read_file( '/path/to/embroidery.dst' ) or
           die "Failed to read data file: $!";
    
        # fiddle with the data structure some. this would make
        # the 201st entry a normal stitch that went 5 units right,
        # and 7 units up
        $emb->{'data'}{'pattern'}[200] = [ $NORMAL, 5, 7 ];

        # supply a new file name, or use the default of 
        # the original file name
        $emb->write_file( '/path/to/new_embroidery.dst' ) or
            die "Failed to write data file: $!";

    This example demonstrates using GD to create an image file using
    Image::Embroidery.

        use Image::Embroidery;
        use GD;
    
        $emb = Image::Embroidery->new();
    
        $emb->read_file( '/path/to/embroidery.dst' ) or
            die "Failed to read data file: $!";

        $im = new GD::Image( $emb->size() );
    
        # the first color you allocate will be the background color
        $black = $im->colorAllocate(0,0,0);

        # the order in which you allocate the rest is irrelevant
        $gray = $im->colorAllocate(128,128,128);
        $red = $im->colorAllocate(255,0,0);
    
        # you can control the thickness of the lines that are used to draw the 
        # image. the default thickness is 1, which will let you see individual
        # stitches. The higher you set the thickness, the smoother the image will
        # look. A thickness of 3 or 4 is good for showing what the finished product
        # will look like
        $im->setThickness(3);

        # the order you specify the colors is the order in which they
        # will be used. you must specify the correct number of colors
        $emb->draw_logo($im, $gray, $red);

        open(IMG, ">", "/path/to/embroidery.png");
        #  make sure you use binary mode when running on Windows
        binmode(IMG);
        print IMG $im->png;
        close(IMG);

    Converting from one format to another

        $emb->read_file( '/path/to/embroidery.exp', 'exp' );
        $emb->save_file( '/path/to/embroidery.dst', 'dst' );

METHODS
    *new*
          my $emb = Image::Embroidery->new();

        The constructor.

    *read_file*
          $emb->read_file($filename);
          $emb->read_file($filename, 'tajima');

        Read an embroidery data file in the specified file format. See FILE
        FORMATS for supported formats. Default is Tajima DST. Returns 0 on
        failure, 1 on success.

    *write_file*
          $emb->write_file();
          $emb->write_file( $filename );
          $emb->write_file( $filename, $format );

        Output the contents of the object's pattern to the specified file,
        using the specified file format. If the filename is omitted, the
        default filename will be the last file that was successfully read
        using *read_file()*. See FILE FORMATS for supported formats. Default
        is Tajima DST. Returns 0 on failure, 1 on success.

    *draw_logo*
          $emb->draw_logo( $gd_image_object, @colors );

        Write an image of the stored pattern to the supplied GD::Image
        object. You must supply the correct number of colors for the
        pattern. Color arguments are those returned by
        GD::Image::colorAllocate. Returns 0 on failure, 1 on success.

    *ignore_header_coordinates*
          my $ignoring = $emb->ignore_header_coordinates;
          $emb->ignore_header_coordinates( 1 );

        Get or set whether to ignore the starting coordinates in the file
        header, and assume that the pattern begins in the center. Some
        programs that generate Tajima DST files put incorrect values into
        the header that cause the image to be off center. Enabling this will
        correct those images, but will display images with correct (but
        offcenter) starting points offset. This MUST be called before
        calling read_file.

    *label*
          my $label = $emb->label();
          $emb->label( $new_label );

        Get or set the label that will be inserted into the file headers, if
        the output format supports it.

    *size*
          my ($x, $y) = $emb->size();

        Returns the X and Y size of the pattern.

    *get_color_changes*
          my $changes = $emb->get_color_changes();

        Return the number of colors changes in the pattern.

    *get_color_count*
          my $colors = $emb->get_color_count();

        Returns the number of colors in the pattern.

    *get_stitch_count*
          my $count = $emb->get_stitch_count();

        Return the total number of stitches in the pattern.

    *get_end_point*
          my ($x, $y) = $emb->get_end_point();

        Returns the position of the last point in the pattern, relative to
        the starting point.

    *get_abs_size*
          my ($plus_x, $minus_x, $plus_y, $minus_y) = $emb->get_abs_size();

        Returns the distance from the starting point to the edges of the
        pattern, in the order +X, -X, +Y, -Y.

FILE FORMATS
    Supported file formats are Tajima DST and Melco EXP. These can be
    specifed to the *read_file()* and *write_file()* routines using the
    strings:

    Tajima DST: 'tajima' or 'dst' Melco EXP: 'melco' or 'exp'

    Strings are case-insensitive. Tajima is always the default.

    A note on Tajima DST files: It seems that many applications that produce
    DST files put incorrect information in the header. I've attempted to
    work around invalid files as much as possible, but occasionally there
    are still problems. If you have a file that loads in another viewer but
    not in this module, let me know and I'll see if I can fix the problem.

AUTHOR
    Kirk Baucom, 

COPYRIGHT AND LICENSE
    Copyright 2003 by Kirk Baucom

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.