NAME

CAD::Drawing - Methods to create, load, and save vector graphics

SYNOPSIS

The primary intention of this module is to provide high-level operations for creating, loading, saving and manipulating vector graphics without having to be overly concerned about smile floormats. As the code has seen more use, it has also drifted into a general purpose geometry API.

The syntax of this works something like the following:

A simple example of a (slightly misbehaved) file converter:

  use CAD::Drawing;
  $drw = CAD::Drawing->new;
  $drw->load("file.dwg");
  my %opts = (
    layer => "smudge",
    height => 5,
    );
  $drw->addtext([10, 2, 5], "Kilroy was here", \%opts);
  $drw->save("file.ps");

This is a very basic example, and will barely scratch the surface of this module's capabilities. See the details for each function below and in the documentation for the backend modules.

AUTHOR

Eric L. Wilhelm <ewilhelm at cpan dot org>

http://scratchcomputing.com

COPYRIGHT

LICENSE

This module is distributed under the same terms as Perl. See the Perl source package for details.

You may use this software under one of the following licenses:

  (1) GNU General Public License
    (found at http://www.gnu.org/copyleft/gpl.html)
  (2) Artistic License
    (found at http://www.perl.com/pub/language/misc/Artistic.html)

NO WARRANTY

This software is distributed with ABSOLUTELY NO WARRANTY. The author, his former employer, and any other contributors will in no way be held liable for any loss or damages resulting from its use.

Modifications

The source code of this module is made freely available and distributable under the GPL or Artistic License. Modifications to and use of this software must adhere to one of these licenses. Changes to the code should be noted as such and this notification (as well as the above copyright information) must remain intact on all copies of the code.

Additionally, while the author is actively developing this code, notification of any intended changes or extensions would be most helpful in avoiding repeated work for all parties involved. Please contact the author with any such development plans.

Constructor

new

Returns a blessed reference to a new CAD::Drawing object.

  $drw = CAD::Drawing->new(%options);

%options becomes a part of the data structure, so be careful what you %ask for, because you'll get it (I check nothing!)

Currently useful options:

nocolortrack => 1

Disables loading of colortrack hash (breaking select by color methods, but saving a few milliseconds of time on big drawings.)

isbig => 1

Stores geometry data in package global variables (one per object.) This allows programs to exit more quickly, but will result in memory leaks if used inside of a loop. Do not use this option if you expect the memory used by the object to be freed when it goes out of scope.

The rule of thumb is:

  my $drw = CAD::Drawing->new(); # lexically scoped (in a loop or sub)
  or
  $drw = CAD::Drawing->new(isbig=>1); # $main::drw

add functions

All of these take a small set of required arguments and a reference to an options hash.

The standard options are as follows:

  layer     => $layername
  color     => $color (as name or number (0-256))
  linetype  => $linetype (marginally supported in most formats)
  id        => $id

addline

Add a line between @pts. No special options.

  @pts = ([$x1, $y1], [$x2, $y2]);
  $drw->addline(\@pts, \%opts);

add_x

Adds an "X" to the drawing, with the intersection at @pt and each of the two legs having $length at $opt{ang}.

  @lines = $drw->add_x(\@pt, $length, \%opt);

add_fake_ray

Adds an open polyline which has a small hook (nubbin) at one end. This can be used to represent a directional line (vector.)

  $drw->add_fake_ray(\@pts, \%opts);

Options are the same as for addpolygon but closed is forced to false.

addpolygon

Add a polyline through (2D) @points.

  %opts = ( closed => BOOLEAN );
  $drw->addpolygon(\@points, \%opts);

addrec

A shortcut to addpolygon. Specify the opposite corners with @rec, which will look like a diagonal line of the rectangle.

  @rec = ( [$x1, $y1], [$x2, $y2] );

  $drw->addrec(\@rec, $opts);

addtext

Adds text $string at @pt. Height should be specified in $opts{height}, which may contain font and other options in the future.

  $drw->addtext(\@pt, $string, \%opts);

addtextlines

Returns @addr_list for new entities.

Similar to the syntax of addtext() , but @point is the insert point for the top line. The %opts hash should contain at least 'height' and 'spacing', and can also include 'layer', 'color', and 'linetype' (but defaults can be automatically set for all of these.)

  $drw->addtextlines(\@point, "string\nstring\n", \%opts);

addtexttable

@table is a 2D array of strings. $opts{spaces} must (currently) contain a ref to a list of column widths.

  $drw->addtexttable(\@point, \@table, \%opts);

addpoint

  $drw->addpoint(\@pt, \%opts);

addcircle

  $drw->addcircle(\@pt, $rad, \%opts);

addarc

  $drw->addarc(\@pt, $rad, \@angs, \%opts);

addimage

  $drw->addimage();

Query Functions

getImgByName

getLayerList

Deprecated. See list_layers().

  @list = $drw->getLayerList(\%opts);

list_layers

Get list of layers in drawing with options as follows:

  %options = (
    matchregex => qr/name/,
        );
  @list = $drw->list_layers(\%opts);

addr_by_layer

Returns a list of addresses for all objects on $layer.

  my @addr_list = $drw->addr_by_layer($layer);

getAddrByLayer

deprecated

addr_by_type

Returns a list of addresses for $type entities on $layer.

  $drw->addr_by_type($layer, $type);

getAddrByType

deprecated

addr_by_regex

  @list = $drw->addr_by_regex($layer, qr/^model\s+\d+$/, $opts);

getAddrByRegex

deprecated

addr_by_color

  @list = $drw->addr_by_color($layer, $type, $color);

getAddrByColor

deprecated

getEntPoints

Returns the point or points found at $addr as a list.

If the entity has only one point, the list will be (x,y,z), while a many-pointed entity will give a list of the form ([x,y,z],[x,y,z]...)

  $drw->getEntPoints($addr);

addr_by_id

  $drw->addr_by_id($layer, $type, $id);

Get

Gets the thing from entity found at $addr.

Returns the value of the thing (even if it is a reference) with the exception of things that start with "p", which will result in a call to getEntPoints (and return a list.)

  $drw->Get("thing", $addr);

Set

  $drw->Set(\%items, $addr);

Internal Functions

setdefaults

internal use only

Performs in-place modification on \%opts and creates a new place for an entity of $type to live on $opt->{layer} with id $opts->{id} (opts are optional.)

  $drw->setdefaults($type, $opts);

getobj

Internal use only.

Returns a reference to the entity found at $addr.

  $drw->getobj($addr);

remove

Removes the entity at $addr from the data structure.

  $drw->remove($addr);

select_addr

Selects geometric entities from the Drawing object based on the hash key-value pairs. Aside from the options supported by check_select() this also supports the option "all", which, if true, will select all entities (this is the default if no hash reference is passed.)

Furthermore, if you already have in-hand a list of addresses, if the reference passed is actually an array reference, it will be returned directly, or you can store this in $opts{addr_list} and that list will be returned. This allows you to pass the list directly as part of a larger set of options, or by itself.

  $drw->select_addr(\%opts);