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 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) 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 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 (and thanks to the new IO.pm plug-in architecture, they will be automagically discovered as they are installed. Each backend module may have additional requirements of its own. CHANGES 0.20 First public release. 0.25 Minor additions to documentation. Enhanced options. Begin interface changes. 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 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); 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); 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 $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.) 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);