.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CAD::Drawing 3"
.TH CAD::Drawing 3 "2008-01-04" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
CAD::Drawing \- Methods to create, load, and save vector graphics
.SH "SYNOPSIS"
.IX Header "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 \s-1API\s0.
.IP "The syntax of this works something like the following:" 4
.IX Item "The syntax of this works something like the following:"
A simple example of a (slightly misbehaved) file converter:
.Sp
.Vb 9
\&  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", \e%opts);
\&  $drw->save("file.ps");
.Ve
.Sp
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.
.SH "AUTHOR"
.IX Header "AUTHOR"
Eric L. Wilhelm <ewilhelm at cpan dot org>
.PP
http://scratchcomputing.com
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This module is copyright (C) 2004\-2006 by Eric L. Wilhelm.  Portions
copyright (C) 2003 by Eric L. Wilhelm and A. Zahner Co.
.SH "LICENSE"
.IX Header "LICENSE"
This module is distributed under the same terms as Perl.  See the Perl
source package for details.
.PP
You may use this software under one of the following licenses:
.PP
.Vb 4
\&  (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)
.Ve
.SH "NO WARRANTY"
.IX Header "NO WARRANTY"
This software is distributed with \s-1ABSOLUTELY\s0 \s-1NO\s0 \s-1WARRANTY\s0.  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.
.SH "Modifications"
.IX Header "Modifications"
The source code of this module is made freely available and
distributable under the \s-1GPL\s0 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.
.PP
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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
These modules are required by Drawing.pm and will be automatically
included by the single \fIuse\fR 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.))
.IP "CAD::Drawing::Defined" 4
.IX Item "CAD::Drawing::Defined"
Generally useful constants and definitions used throughout the
CAD::Drawing toolkit.
.IP "CAD::Drawing::Manipulate" 4
.IX Item "CAD::Drawing::Manipulate"
Entity manipulation methods.
.IP "CAD::Drawing::Manipulate::Transform" 4
.IX Item "CAD::Drawing::Manipulate::Transform"
Matrix transform methods.
.IP "CAD::Drawing::Manipulate::Graphics" 4
.IX Item "CAD::Drawing::Manipulate::Graphics"
Deals with embedded image definitions.
.IP "CAD::Drawing::Calculate" 4
.IX Item "CAD::Drawing::Calculate"
Calculations and coordinate system transforms.
.IP "CAD::Drawing::Calculate::Finite" 4
.IX Item "CAD::Drawing::Calculate::Finite"
Fitting and bounding.
.IP "CAD::Drawing::IO" 4
.IX Item "CAD::Drawing::IO"
Input/Output plugin mechanism.
.PP
All of the backend IO::* modules are optional, and will be automagically
discovered as they are installed.  See CAD::Drawing::IO for details.
.SH "Constructor"
.IX Header "Constructor"
.Sh "new"
.IX Subsection "new"
Returns a blessed reference to a new CAD::Drawing object.
.PP
.Vb 1
\&  $drw = CAD::Drawing->new(%options);
.Ve
.PP
%options becomes a part of the data structure, so be careful what you
\&\f(CW%ask\fR for, because you'll get it (I check nothing!)
.IP "Currently useful options:" 4
.IX Item "Currently useful options:"
.PD 0
.IP "nocolortrack => 1" 4
.IX Item "nocolortrack => 1"
.PD
Disables loading of colortrack hash (breaking select by color methods,
but saving a few milliseconds of time on big drawings.)
.IP "isbig => 1" 4
.IX Item "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.
.Sp
The rule of thumb is: 
.Sp
.Vb 3
\&  my $drw = CAD::Drawing->new(); # lexically scoped (in a loop or sub)
\&  or
\&  $drw = CAD::Drawing->new(isbig=>1); # $main::drw
.Ve
.SH "add functions"
.IX Header "add functions"
All of these take a small set of required arguments and a reference to
an options hash.
.PP
The standard options are as follows:
.PP
.Vb 4
\&  layer     => $layername
\&  color     => $color (as name or number (0-256))
\&  linetype  => $linetype (marginally supported in most formats)
\&  id        => $id
.Ve
.Sh "addline"
.IX Subsection "addline"
Add a line between \f(CW@pts\fR.  No special options.
.PP
.Vb 2
\&  @pts = ([$x1, $y1], [$x2, $y2]);
\&  $drw->addline(\e@pts, \e%opts);
.Ve
.Sh "add_x"
.IX Subsection "add_x"
Adds an \*(L"X\*(R" to the drawing, with the intersection at \f(CW@pt\fR and each of the
two legs having \f(CW$length\fR at \f(CW$opt\fR{ang}.
.PP
.Vb 1
\&  @lines = $drw->add_x(\e@pt, $length, \e%opt);
.Ve
.Sh "add_fake_ray"
.IX Subsection "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.)
.PP
.Vb 1
\&  $drw->add_fake_ray(\e@pts, \e%opts);
.Ve
.PP
Options are the same as for addpolygon but closed is forced to false.
.Sh "addpolygon"
.IX Subsection "addpolygon"
Add a polyline through (2D) \f(CW@points\fR.
.PP
.Vb 2
\&  %opts = ( closed => BOOLEAN );
\&  $drw->addpolygon(\e@points, \e%opts);
.Ve
.Sh "addrec"
.IX Subsection "addrec"
A shortcut to addpolygon. Specify the opposite corners with \f(CW@rec\fR, which
will look like a diagonal line of the rectangle.
.PP
.Vb 1
\&  @rec = ( [$x1, $y1], [$x2, $y2] );
.Ve
.PP
.Vb 1
\&  $drw->addrec(\e@rec, $opts);
.Ve
.Sh "addtext"
.IX Subsection "addtext"
Adds text \f(CW$string\fR at \f(CW@pt\fR.  Height should be specified in \f(CW$opts\fR{height},
which may contain font and other options in the future.
.PP
.Vb 1
\&  $drw->addtext(\e@pt, $string, \e%opts);
.Ve
.Sh "addtextlines"
.IX Subsection "addtextlines"
Returns \f(CW@addr_list\fR for new entities.
.PP
Similar to the syntax of \fIaddtext()\fR , but \f(CW@point\fR is the insert point for
the top line.  The \f(CW%opts\fR 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.)
.PP
.Vb 1
\&  $drw->addtextlines(\e@point, "string\enstring\en", \e%opts);
.Ve
.Sh "addtexttable"
.IX Subsection "addtexttable"
@table is a 2D array of strings.  \f(CW$opts\fR{spaces} must (currently) 
contain a ref to a list of column widths.
.PP
.Vb 1
\&  $drw->addtexttable(\e@point, \e@table, \e%opts);
.Ve
.Sh "addpoint"
.IX Subsection "addpoint"
.Vb 1
\&  $drw->addpoint(\e@pt, \e%opts);
.Ve
.Sh "addcircle"
.IX Subsection "addcircle"
.Vb 1
\&  $drw->addcircle(\e@pt, $rad, \e%opts);
.Ve
.Sh "addarc"
.IX Subsection "addarc"
.Vb 1
\&  $drw->addarc(\e@pt, $rad, \e@angs, \e%opts);
.Ve
.Sh "addimage"
.IX Subsection "addimage"
.Vb 1
\&  $drw->addimage();
.Ve
.SH "Query Functions"
.IX Header "Query Functions"
.Sh "getImgByName"
.IX Subsection "getImgByName"
.Sh "getLayerList"
.IX Subsection "getLayerList"
Deprecated.  See \fIlist_layers()\fR.
.PP
.Vb 1
\&  @list = $drw->getLayerList(\e%opts);
.Ve
.Sh "list_layers"
.IX Subsection "list_layers"
Get list of layers in drawing with options as follows:
.PP
.Vb 4
\&  %options = (
\&    matchregex => qr/name/,
\&        );
\&  @list = $drw->list_layers(\e%opts);
.Ve
.Sh "addr_by_layer"
.IX Subsection "addr_by_layer"
Returns a list of addresses for all objects on \f(CW$layer\fR.
.PP
.Vb 1
\&  my @addr_list = $drw->addr_by_layer($layer);
.Ve
.Sh "getAddrByLayer"
.IX Subsection "getAddrByLayer"
deprecated
.Sh "addr_by_type"
.IX Subsection "addr_by_type"
Returns a list of addresses for \f(CW$type\fR entities on \f(CW$layer\fR.
.PP
.Vb 1
\&  $drw->addr_by_type($layer, $type);
.Ve
.Sh "getAddrByType"
.IX Subsection "getAddrByType"
deprecated
.Sh "addr_by_regex"
.IX Subsection "addr_by_regex"
.Vb 1
\&  @list = $drw->addr_by_regex($layer, qr/^model\es+\ed+$/, $opts);
.Ve
.Sh "getAddrByRegex"
.IX Subsection "getAddrByRegex"
deprecated
.Sh "addr_by_color"
.IX Subsection "addr_by_color"
.Vb 1
\&  @list = $drw->addr_by_color($layer, $type, $color);
.Ve
.Sh "getAddrByColor"
.IX Subsection "getAddrByColor"
deprecated
.Sh "getEntPoints"
.IX Subsection "getEntPoints"
Returns the point or points found at \f(CW$addr\fR as a list.
.PP
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]...)
.PP
.Vb 1
\&  $drw->getEntPoints($addr);
.Ve
.Sh "addr_by_id"
.IX Subsection "addr_by_id"
.Vb 1
\&  $drw->addr_by_id($layer, $type, $id);
.Ve
.Sh "Get"
.IX Subsection "Get"
Gets the thing from entity found at \f(CW$addr\fR.
.PP
Returns the value of the thing (even if it is a reference) with the
exception of things that start with \*(L"p\*(R", which will result in a call to
getEntPoints (and return a list.)
.PP
.Vb 1
\&  $drw->Get("thing", $addr);
.Ve
.Sh "Set"
.IX Subsection "Set"
.Vb 1
\&  $drw->Set(\e%items, $addr);
.Ve
.SH "Internal Functions"
.IX Header "Internal Functions"
.Sh "setdefaults"
.IX Subsection "setdefaults"
internal use only
.PP
Performs in-place modification on \e%opts and creates a new place for an
entity of \f(CW$type\fR to live on \f(CW$opt\fR\->{layer} with id \f(CW$opts\fR\->{id} (opts are
optional.)
.PP
.Vb 1
\&  $drw->setdefaults($type, $opts);
.Ve
.Sh "getobj"
.IX Subsection "getobj"
Internal use only.
.PP
Returns a reference to the entity found at \f(CW$addr\fR.
.PP
.Vb 1
\&  $drw->getobj($addr);
.Ve
.Sh "remove"
.IX Subsection "remove"
Removes the entity at \f(CW$addr\fR from the data structure.
.PP
.Vb 1
\&  $drw->remove($addr);
.Ve
.Sh "select_addr"
.IX Subsection "select_addr"
Selects geometric entities from the Drawing object based on the hash
key-value pairs.  Aside from the options supported by \fIcheck_select()\fR
this also supports the option \*(L"all\*(R", which, if true, will select all
entities (this is the default if no hash reference is passed.)
.PP
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 \f(CW$opts\fR{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.
.PP
.Vb 1
\&  $drw->select_addr(\e%opts);
.Ve