NAME
CAD::OpenSCAD - A module to generate OpenSCAD files for 3D Object creation in Perl
SYNOPSIS
use CAD::OpenSCAD;
my $scad=new OpenSCAD;
$scad->cube("main",[10,10,10],1)
->cylinder("hole",{r=>4,h=>20},1)
->difference("newObject","main","hole")
->build("newObject")
->save("testScad");DESCRIPTION
*** From Version 0.14 the API change to make class the same name as module file means that the className is now OpenSCAD (was SCAD before *** CAD is not really something that has had significant recent Perl attention. The OenSCAD framework allows the use of scripted generation and manipulation of 3D objects, and this module attempts to make this accessible in Perl. Object::Pad, a modern OOP paradigm, is used but deliberately not using its full features. The OpenSCAD GUI can be used to display outputs, although .STL, .PNG,and .SCAD files (and others) may also be generated. The example script car.pl replicates one of the tutorial objects. As you can see, the OpenSCAD object is returned after every operation, allowing daisy-chaining of operations. The items within are named for easy identification and often appear in the .scad file generated as comments. These items can be collected, and built (to generate the OpenSCAD script), and potentially saved in various formats using OpenSCAD, or injected directly into the GUI tool for further fine-tuning. (OpenSCAD is required to be installed for rendering)
At this point the main goal is to have the ability to generate 3D objects within perl programs. With this tool one can use data acquired in perl programs to create 3D objects without having to know the OpenSCAD scripting language, although knowing this would allow fuller exploitation of the native OpenSCAD powers. One could use the output for
.gif?raw=true)
MAIN METHODS
Creating an OpenSCAD object is by the standard methods. Optional parameters are hash key=>value pairs. valid keys are fa, fs and tab
use CAD::OpenSCAD;
my $scad=new OpenSCAD();
# optionally can add fs, fa and tab on intialisation
# e.g my $scad=new OpenSCAD(fs=>1, fa=>0.4, tab=>0);New elements can be added to this OpenSCAD object; each object is named for subsequent transformations
set_fs set_fa set_tab set_vpt set_vpd set_vpf set_vp set_preview
Using these, one can set parameters for the surface generation and script outputs. e.g.
$scad->set_fa(10) 3D Primitive Shapes
cube
cube creates a cube element e.g.
$scad->cube("bodyBase",[60,20,10],1);The first parameter is the name of the element (if the named element exists already, it will be over-written). The second parameter is an arrayref of three dimensions. The third parameter defines whether the element is centered in the origin (a true value here centers the element)
cylinder
Creates a cylinder element e.g.
$scad->cylinder("wheel",{h=>2,r=>8},1);The first parameter is the name of the element (if the named element exists already, it will be over-written). The second parameter is a hashref of defining radius and height. The third parameter defines whether the element is centered on the origin (a true value here centers the element)
sphere
Creates a sphere element e.g.
$scad->sphere("ball",{r=>8});first parameter is the name of the element (if the named element exists already, it will be over-written).The second parameter is a hashref of defining radius of the sphere.
Transformations
translate
Moves an element by name a specified displacement in X,Y,Z directions e.g.
$scad->cube("bodyTop",[30,20,10],1)->translate("bodyTop",[0,0,5]);The first parameter is the name of the element (the element must exist already). The second parameter is an arrayref of three elements defining displacement.
rotate
Rotates an element by name around X,Y,Z axes about the origin [0,0,0].e.g.
$scad->cylinder("wheel",{h=>2,r=>8},1)->rotate("wheel",[90,0,0]);The first parameter is the name of the element (the element must exist already).The second parameter is an arrayref of three rotations in degrees.
mirror
Mirrors an element by name about a plane. That plane is defined by the normal to that vector, and the plane goes through the origin.
$scad->cube([2,2,2])->mirror("cube",[1,0,0]);The first parameter is the name of the element (the element must exist already). The second parameter is an arrayref containg the planes normal e.g.[1,0,0] implies a mirroring about the X-axis.
resize
Resizes an element by name to specified dimensions in X,Y,Z directions.e.g.
$scad->cube("bodyTop",[30,20,10],1)->resize("bodyTop",[3,2,6]);The first parameter is the name of the element (the element must exist already).The second parameter is an arrayref of three scale factors.
scale
Scales an element by name by specified ratios in X,Y,Z directions.e.g.
$scad->cube("bodyTop",[30,20,10],1)->scale("bodyTop",[1,2,0.5]);The first parameter is the name of the element (the element must exist already). The second parameter is an arrayref of three scale factors.
multimatrix
Multiplies the geometry of all child elements with the given affine transformation matrix, where the matrix is 4X3, or a 4X4 matrix with the 4th row always forced to [0,0,0,1].
skew
Uses MultiMatrix to transform a item by skewing in xy, yx, zy, yz, xz, zx planes. this uses a matrix described in this gist (see corrections). e.g.
$scad ->cube("box",[10,10,20])->skew("box",{xz=>-25});offset
Offset generates a new 2d interior or exterior outline from an existing outline. There are two modes of operation: radial and delta.
hull
Displays the convex hull of child nodes.
my $chart=new OpenSCAD;
my $pos=[0,0,0]; my @cubes=(); my @hulls=();
for (0..100){ # a hundred randomly displaced cubes
$chart->cube("dot$_",3)->translate("dot$_",$pos);
$pos=[$pos->[0]+((-20..20)[rand()*40]),$pos->[1]+((-20..20)[rand()*40]),$pos->[2]+((-20..20)[rand()*40])];
push @cubes,"dot$_";
}
for (0..100){ # hulls between sequential pairs
$chart->hull("hull$_",$cubes[$_],$cubes[$_-1]);
push @hulls,"hull$_";
}
$chart->build(@hulls)->save("hull");minkowski
Boolean Operations
union
Implicitly joins multiple elements into one element.e.g.$scad->union("wheel",qw/wheel nut nut1 nut2 nut3/); the first item is the name of the new element created, the following elements are elements to be joined together. If an element with the name of the first parameter does not exist, it is created, otherwise it is over-written.
difference
Subtracts one or more elements from one element and creates a new element. e.g.
$scad->difference("wheel",qw/wheel nut nut1 nut2 nut3/); The first parameter`"wheel"` in this example is the name of the new element created, the second parameter refers to the item that all other elements are subtracted from. If an element with the name of the first parameter does not exist, it is created, otherwise it is over-written. So this statement takes the item "wheel" (the second parameter), subtracts all the nuts, and overwrites the code in "wheel" (first parameter).
intersection
Creates an element representing the overlapping parts of 2 or more elements .e.g.
$scad->intersection("overlap",qw/item1 item2 item3/);The first parameter is the name of the new element created, the other names refer to elements which overlap neach other.
2D Primitive Shapes
circle
A 2D drawing primitive that creates a circle that may be extruded to create other 3D structures. e.g
$scad->circle("circle",{r=>5});square
a 2D drawing primitive that creates a rectangle that may be extruded to create other 3D structures. e.g
$scad->square("square",[10,10]);
polygon
A 2D drawing primitive that creates a polygon that may be extruded to create other 3D structures . Example:-
my $extrusion=new OpenSCAD;
$extrusion->variable({p0=>[0, 0],p1 => [0, -30],p2 => [15, 30],p3=> [35, 20],p4 => [35, 0]})
->variable("points",[qw/p0 p1 p2 p3 p4 /] )
->polygon("poly","points")
->linear_extrude("poly",{height=>100,twist=>180}); text
Allows 2D text shapes to be created, that may be extruded and manipulated like other items e.g.
$output->text($label,{text=>$textString,size=>$size,font=>$fontName})or
$output->text($label,"Hello World")to just use defaults.
Extrusion
rotate_extrude
A method to extrude a 2D shape while rotating invokes similar to liner_extrude
my $extrusion=new OpenSCAD;
$extrusion->circle("circle",{r=>5})
->translate("circle",[10,0,0])
->rotate_extrude("circle",{angle=>180});liner_extrude
A method to extrude a 2D shape see above for example
color
colors an item e.g. .
$scad->cylinder("ball",{r=>8})->color("ball","green");clone
Creates copies of elements with same features. e.g.
$car->clone("axle",qw/frontaxle rearaxle/);This just copies the code for the element into new elements, for subsequent transformation (otherwise all the elements are positioned in the same place overlying one another)
variable
Creates variables that SCAD can use for customising objects easily (see polygon example above)
Build and Save
build
Collects the elements specified (i.e. not all the elements, just the items required for the build) and all the variables to generate a scad file. The scad file generated include all the variables defined, the modules built and the libraries used
save
saves the .scad file, and also uses openscad to generate images or 3D objects from the script, or open it in openSCAD directly after building the shape;
$scad->build("ext")->save("extrusion");builds a scad file with the item "ext", then saves the scad file, and automatically opens OpenSCAD file. if another parameter passed, the generates a corresponding file, from one of (stl|png|t|off|wrl|amf|3mf|csg|dxf|svg|pdf|png|echo|ast|term|nef3|nefdbg) e.g. $scad->save("extrusion","png")
scadItem
This is class for future use to allow an item in OpenSCAD to know its dimensions vertexes, faces and orientations. For now it works with polyhedrons to allow distortions. It is possible that many OpenSCAD primitivs will be convertable to scadItem polyhedra to allow such manipulations. It is inserted as $scad->items->{"item_name"}, and during the $scad->build("item_name") the script is gnerated by the script method below.
scadItem::point()
gets or sets the point at a certain index position in <scadItem>->args->{points} e.g. <scadItem>->point($index) or <scadItem>->point($index,$newPoint)
scadItem::scale
scales the coordinates of a point or set of points (passed as index poitions)
scadItem::shear
translates the coordinates of a point or set of points (passed as index poitions)
scadItem::adjacent()
retrieves a list of indices of a points with edges connecting a point
scadItem::remove
removes a point or a set of points from the faces (but not from the points list), and regenerates a new face to restore the object
SUPPORT
COPYRIGHT AND DISCLAIMERS
Copyright (c) 2025 Saif Ahmed.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.
AUTHOR
SAIFTYNET
CONTRIBUTORS
jmlynesjr