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.

The syntax of this works something like the following:

A simple example of a file converter:

use CAD::Drawing;
$drw = CAD::Drawing->new;
$drw->load("file.dwg");
$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 sbcglobal dot net
http://pages.sbcglobal.net/mycroft

COPYRIGHT

This module is copyright (C) 2003 by Eric L. Wilhelm and A. Zahner Co.

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 and his employer 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.

SEE ALSO

These modules are required by Drawing.pm and will be automatically included by the single use Drawing; statement. No functions are exported to the main program's namespace (unless you try to use CAD::Drawing::Defined from your main code (don't do that.))

CAD::Drawing::Manipulate
CAD::Drawing::Defined
CAD::Drawing::Calculate
CAD::Drawing::Calculate::Finite
CAD::Drawing::IO
CAD::Drawing::IO::OpenDWG
CAD::Drawing::IO::PostScript
CAD::Drawing::IO::Image

While it might be problematic to have to install a huge tree worth of modules just to use one, from a programming and design standpoint, it is much easier to deal with so much code when it is broken into separate pieces. Additionally, all of the backend IO modules are optional (though the use statements aren't setup that way (anyone want to setup a Makefile.PL that will take care of this?))

Each backend module may have additional requirements of its own.

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);

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

$drw->addtexttable();

addpoint

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

addcircle

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

addarc

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

addimage

$drw->addimage();

Query Functions

getLayerList

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

getAddrByLayer

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

@addr_list = $drw->getAddrByLayer($layer);

getAddrByType

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

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

getAddrByRegex

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

getAddrByColor

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

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);

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

$drw->remove();

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.)

$drw->select_addr(\%opts);

cpanm CAD::Drawing

perl -MCPAN -e shell
install CAD::Drawing