Package: yapCAD
yet another procedural CAD and computational geometry system written in
python 3yapCADimagewhat’syapCADfor?First and foremost,yapCADis a framework for creatingparametric,
procedural, andgenerativedesign
systems. You can also useyapCADfor other CAD, CAM, and
computational geometry purposes.software statusyapCADis still very much inbeta, although it is already being
used by for professional engineering purposes. If you are usingyapCADin interesting ways, feel free to let us know in theyapCAD
discussionsforumyapCADinstallation, documentation, and examplesinstallationyapCADis a pure python library, so no special steps are required
for installation. You can install it a variety of ways, but the
recommended method is to use pip to install it into your localsite-packagesdirectory, as follows:pip install yapCAD --userYou can also clone the github repository and install from source:git clone https://github.com/rdevaul/yapCAD.git
cd yapCAD
python setup.py install --userexamplesTheyapCADgithub repository includes examples. To run the examples,
clone the github repository as shown above, and make sure that your
PYTHONPATH includes the cloned top-levelyapCADdirectory. You will
find the examples in theyapCAD/examplesdirectory.For a fully worked parametric design system, see theboxcutexample.documentationOnlineyapCADdocumentation can be found here:https://yapcad.readthedocs.io/en/latest/— for some reasonreadthedocs.ioisn’t generating the full module documentation, so
you might want to build a local copy, as described below.To build the HTMLyapCADdocumentation locally, first make sure you
have the sphinx package installed:pip install sphinx --userThen clone the github repository as shown above,cdto theyapCADdirectory, and typemake -C docs htmlThis will build the HTML documents in thebuild/sphinx/htmldirectory. You can also build documentation in the other formats
supported by Sphinx. See theSphinx
documentationfor more
information.yapCADgoalsThe purpose ofyapCADis to support 2D and 3D computational geometry
and parametric, procedural, and generative design projects in python3.yapCADis designed to support multiple rendering back-ends, such
that a relatively small amount of code is necessary to add support for a
2D or 3D cad or drawing file format. At present,yapCADsupports the
AutoCad DXF file format for creating two-dimensional drawings and OpenGL
for creating interactive 2D and 3D renderings.The foundations ofyapCADare grounded in decades of the author’s
experience with graphics system programming, 3D CAD and simulation.yapCADhas an underlying framework and architecture designed to
support sophisticated computational geometry and procedural CAD
applications. At the same time, the design ofyapCADshould make
easy stuff relatively easy, and the more advanced stuff possible.The initial implementation ofyapCADprovides DXF file creation
support through the awesomeezdxfpackage, and interactive OpenGL visualization using the amazingpygletpackage.yapCADexamples(for a more complete list, see theexamples folder)It’s pretty easy to make a DXF drawing withyapCAD. Here is an
example:from yapcad.ezdxf_drawable import *
from yapcad.geom import *

#set up DXF rendering
dd=ezdxfDraw()
dd.filename = "example1-out"

## make dxf-renderable geometry

# make a point located at 10,10 in the x-y plane, rendered as a small
# red cross and circle
dd.pointstyle = 'xo' # also valid are 'x' or 'o'
dd.linecolor = 1 # set color to red (DXF index color 1)
dd.draw(point(10,10))

# make a line segment between the points -5,10 and 10,-5 in the x-y plane
# and draw it in white

dd.linecolor='white' # set color by name
dd.draw(line(point(-5,10),
             point(10,-5)))

# make an arc with a center at 0,3 with a radius of 3, from 45 degrees
# to 135 degrees, and draw it in aqua

dd.linecolor=[0,255,255] # RGB tripple, corresponds to 'aqua'
dd.draw(arc(point(0,3),3,45,135))

# write out the geometry as example1-out.dxf
dd.display()TheyapCADsystem isn’t just about rendering, of course, it’s about
computational geometry. For example, if you want to calculate the
intersection of lines and arcs in a plane, we have you covered:from yapcad.geom import *

# define some points
a = point(5,0)
b = point(0,5)
c = point(-3,0)
d = point(10,10)

# make a couple of lines
l1 = line(a,b)
l2 = line(c,d)

# define a semicircular arc centered at 2.5, 2,5 with a radius of 2.5
# extending from 90 degrees to 135 degrees

arc1=arc(point(2.5,2.5),2.5,90.0,270.0)

# calculate the intersection of lines l1 and l2
int0 = intersectXY(l1,l2)

# calculate the intersection of the line l1 and the arc arc1
int1 = intersectXY(l1,arc1)

print("intersection of l1 and l2:",vstr(int0))
print("intersection of l1 and arc1:",vstr(int1))And of courseyapCADsupports calculating intersections between any
simple and compound, or compound and compound geometry object.There are lots moreexamplesavailable to
demonstrate the various computational geometry and rendering
capabilities ofyapCAD, including 3D geometry and OpenGL rendering.yapCADgeometryyapCADdistinguishes between “pure” geometric elements, such as
lines, arcs,etc., and drawn representations of those things, which
might have attributes like line color, line weight, drawing layer,etc.This distinction is important, because the pure geometry exists
independent of these attributes, which are themselves rendering-system
dependent.More importantly, for every geometric element you decide to draw, there
will typically be many more — perhaps dozens — that should not be in the
final rendering. By separating these two elements — computation and
rendering —yapCADmakes them both more intentional and reduces the
likelihood of certain type of drawing-quality issues, such as redundant
or spurious drawing elements, that can cause confusion problems for
computer-aided manufacturing (CAM).For example, you might construct a finished drawing that includes a
drill pattern that consists of circles (drill holes with centers) that
follow a complex, geometrically constrained pattern. This pattern is
itself the result of numerous computational geometry operations, perhaps
driven by parameters relating to the size and shape of other parts.In a program like Autodesk’s Fusion360, you would typically use
construction lines and constraints to create the underlying geometric
pattern. These additional construction elements would have to be removed
in order to make a clean DXF export of your drawing. On more than one
occasionyapCAD’s author has created headaches by failing to
remove some of these elements, confusing CAM technicians, causing
delays, and sometimes resulting in expensive part fabrication errors.Thus,yapCADallows you to work freely with computational geometry
without cluttering up your drawing page, since you specifically decide
what to draw. It also means you can do computational geometry inyapCADwithout ever invoking a rendering system, which can be useful
when incorporating these geometry operations as part of a larger
computational system, such as a tool-path generator.As a rule, inyapCADpure geometry representations capture only the
minimum necessary to perform computational geometry, and the rest gets
dealt with by the rendering system, which are subclasses ofDrawablethat actually make images, CAD drawings,etc.vector representation inyapCADFor the sake of uniformity, allyapCADvectors are stored as
projective geometry 4-vectors. (see discussion inarchitecture,
below) However, most of the time you will work with them as though they
are 3-vectors or 2-vectors.It would be annoying to have to specify the redundant coordinates you
aren’t using every time you specify a vector, soyapCADprovides you
with thevectfunction. It fills in defaults for the z and w
parameters you may not want to specify.e.g.>>> from yapcad.geom import *
>>> vect(10,4)
[10, 4, 0, 1]
>>> add(vect(10,4),vect(10,9))  ## add operates in 3-space
[20, 13, 0, 1.0]Of course, you can specify all three (or even four) coordinates usingvect.Since it gets ugly to look at a bunch of [x, y, z, w] lists that all end
in0, 1]when you are doing 2D stuff,yapCADprovides a
convenience functionvstrthat intelligently convertsyapCADvectors (and lists that contain vectors, such as lines, triangles, and
polygons) to strings, assuming that as long as z = 0 and w = 1, you
don’t need to see those coordinates.>>> from yapcad.geom import *
>>> a = sub(vect(10,4),vect(10,9)) ## subtract a couple of vectors
>>> a
[0, -5, 0, 1.0]
>>> print(vstr(a)) ## pretty printing, elide the z and w coordinates
>>> [0, -5]pure geometryPure geometric elements inyapCADform the basis for computational
geometry operations, including intersection and inside-outside testing.
Pure geometry can also be drawn, of course — seedrawable geometrybelow.In general,yapCADpure geometry supports the operations of
parametric sampling, intersection calculation, inside-outside testing
(for closed figures), “unsampling” (going from a point on the figure to
the sampling parameter that would produce it), and bounding box
calculation.yapCADgeometry is based on projective or homogeneous
coordinates, thus supporting generalized affine transformations; See the
discussion inarchitecture, below.simple (non-compound) pure geometric elementsSimple, which is to say non-compound, geometry includes vectors, points,
and lines. A vector is a list of exactly four numbers, each of which is
a float or integer. A point is a vector that lies in a w > 0 hyperplane;
Points are used to represent transformable coordinates inyapCADgeometry. A line is a list of two points.Simple geometry also includes arcs. An arc is a list of a point and a
vector, followed optionally by another point. The first list element is
the center of the arc, the second is a vector in the w=-1 hyperplane
(for right-handed arcs) whose first three elements are the scalar
parameters[r, s, e]: the radius, the start angle in degrees, and
the end angle in degrees. The third element (if it exists) is the normal
for the plane of the arc, which is assumed to be[0, 0, 1](the x-y
plane) if it is not specified. Arcs are by default right-handed, but
left-handed arcs are also supported, with parameter vectors lying in the
w=-2 hyperplane.compound figuresA list of more than two points represents a multi-vertex polylines. If
there are at least four points in the list and the last point is the
same as the first, the polyline figure is closed. (We sometimes refer to
these point-list polygons or polylines aspoly()entities.) Closed
coplanar polylines are drawn as polygons and may be subject to
inside-outside testing. Like other elements of pure geometry, polylines
are subject to sampling, unsampling, intersection calculation,etc.If instead of sharp corners you want closed or open figures with rounded
corners, you should usePolylineorPolygoninstances. Instances
of these classes are used for representing compound geometric elements
in an XY plane with C0 continuity. They differ from the point-list-basedpoly()representation in that the elements of aPolylineorPolygoncan include lines and arcs as well as points. These elements
need not be contiguous, as successive elements will be automatically
joined by straight lines.Polygonsare special in that they are
always closed, and that any full circle elements are interpreted as
“rounded corners,” with the actual span of the arc calculated after
tangent lines are drawn.ThePolygonclass supports boolean operations, as described below,
and also supports thegrow()operation that makes generating a
derived figure that is bigger by a fixed amount easy. This grow feature
is very useful for many engineering operations, such as creating an
offset path for drill holes, CAM paths, etc.boolean operations onPolygoninstancesyapCADsupports boolean set operations onPolygoninstances,
allowing you to construct more complex two-dimensional figures from
union, intersection, and difference operations. Note that the difference
operation can result in the creation of disjoint geometry in the form of
two or more closed figures with positive area (see below), or closed
figures with holes.SeeExample 11for a relatively simple
example of boolean operations, andExample
12for a more complex example.yapCADemploys the convention that closed figures with right-handed
geometry (increasing the sampling parameter corresponds to points that
trace a counter-clockwise path) represent “positive” area, and that
closed figures with left-handed geometry represent holes. This
distinction is currently not operational, but will be important for
future development such as turning polygons into rendered surfaces and
extruding these surfaces into 3D.disjoint compound geometryBoolean difference operations can result in disjoint figures. It is also
possible to combineyapCADgeometric elements in geometry lists,
which is to say a list of zero or more elements ofyapCADpure
geometry, which enforce no continuity constraints. Geometry lists
provide the basis foryapCADrendering.drawable geometryThe idea is that you will do your computational geometry with “pure”
geometry, and then generate rendered previews or output with one or moreDrawableinstances.InyapCAD, geometry is rendered with instances of subclasses ofDrawable, which at present includeezdxfDrawable, a class for
producing DXF renderings using the awesomeezdxfpackage, andpygletDrawable, a class for interactive 2D and 3D OpenGL rendering.To setup a drawing environment, you create an instance of theDrawablebase class corresponding to the rendering system you want
to use.To draw, create the pure geometry and then pass that to the drawbles’sdraw()method. To display or write out the results you will invoke
thedisplaymethod of the drawable instance.supported rendering systemsDXF rendering usingezdxfand interactive OpenGL rendering usingpygletare currently supported, and the design ofyapCADmakes
it easy to support other rendering backends.yapCADarchitectureUnder the hood,yapCADis usingprojective
coordinates,
sometimes called homogeneous coordinates, to represent points as 3D
coordinates in the w=1 hyperplane. If that sounds complicated, its
because it is. :P But it does allow for a wide range of geometry
operations, specificallyaffine
transformsto be represented as composable transformation matrices. The benefits of
this conceptual complexity is an architectural elegance and generality.Support for affine transforms is at present rudimentary, but once a
proper matrix transform stack is implemented it will allow for the
seamless implementation and relatively easy use of a wide range of
transformation and projection operations.What does that buy you? It means that under the hood,yapCADuses
the same type of geometry engine that advanced CAD and GPU-based
rendering systems use, and should allow for a wide range of
computational geometry systems, possibly hardware-accelerated, to be
built on top of it.The good news is that you don’t need to know about homogeneous
coordinates, affine transforms, etc., to useyapCAD. And most of the
time you can pretend that your vectors are just two-dimensional if
everything you are doing happens to lie in the x-y plane.So, if you want to do simple 2D drawings, we have you covered. If you
want to build a GPU-accelerated constructive solid geometry system, you
can do that, too.NoteThis project has been set up using PyScaffold 3.2.3. For details and
usage information on PyScaffold seehttps://pyscaffold.org/.