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, <kbaucom@schizoid.com>

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.