CAD::Drawing - Methods to create, load, and save vector graphics
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.
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.
Eric L. Wilhelm <ewilhelm at cpan dot org>
http://scratchcomputing.com
This module is copyright (C) 2004-2006 by Eric L. Wilhelm. Portions copyright (C) 2003 by Eric L. Wilhelm and A. Zahner Co.
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)
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.
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.
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.))
Generally useful constants and definitions used throughout the CAD::Drawing toolkit.
Entity manipulation methods.
Matrix transform methods.
Deals with embedded image definitions.
Calculations and coordinate system transforms.
Fitting and bounding.
Input/Output plugin mechanism.
All of the backend IO::* modules are optional, and will be automagically discovered as they are installed. See CAD::Drawing::IO for details.
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!)
Disables loading of colortrack hash (breaking select by color methods, but saving a few milliseconds of time on big drawings.)
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
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
Add a line between @pts. No special options.
@pts = ([$x1, $y1], [$x2, $y2]); $drw->addline(\@pts, \%opts);
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);
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.
Add a polyline through (2D) @points.
%opts = ( closed => BOOLEAN ); $drw->addpolygon(\@points, \%opts);
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);
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);
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);
@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);
$drw->addpoint(\@pt, \%opts);
$drw->addcircle(\@pt, $rad, \%opts);
$drw->addarc(\@pt, $rad, \@angs, \%opts);
$drw->addimage();
Deprecated. See list_layers().
@list = $drw->getLayerList(\%opts);
Get list of layers in drawing with options as follows:
%options = ( matchregex => qr/name/, ); @list = $drw->list_layers(\%opts);
Returns a list of addresses for all objects on $layer.
my @addr_list = $drw->addr_by_layer($layer);
deprecated
Returns a list of addresses for $type entities on $layer.
$drw->addr_by_type($layer, $type);
@list = $drw->addr_by_regex($layer, qr/^model\s+\d+$/, $opts);
@list = $drw->addr_by_color($layer, $type, $color);
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);
$drw->addr_by_id($layer, $type, $id);
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);
$drw->Set(\%items, $addr);
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);
Internal use only.
Returns a reference to the entity found at $addr.
$drw->getobj($addr);
Removes the entity at $addr from the data structure.
$drw->remove($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);
To install CAD::Drawing, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CAD::Drawing
CPAN shell
perl -MCPAN -e shell install CAD::Drawing
For more information on module installation, please visit the detailed CPAN module installation guide.