drafting

Planar geometry, technical drawing and solid modelling for GNU Octave.

The package is the drafting layer an engineering design package builds on, and an alternative to OpenSCAD written in Octave itself: compute geometry, model a part, draw it, and send it to a CAD program as DXF or STEP, to a slicer as STL or 3MF, to a report as LaTeX, or to the screen. Solids come through Open CASCADE. All geometry is in millimetres.

• Outlines and curves: polylines with arcs, splines, paths in 3-D, and regions with holes, which combine, offset, round, hull, mirror and repeat as OpenSCAD's 2-D shapes do, their arcs kept exact; text as outlines.
• Solids: primitives, and extrusions, revolutions, lofts, sweeps and helices of regions; booleans; holes, pockets, fillets, full rounds, chamfers and shells on edges and faces chosen by what they are; tapped holes and ISO metric threads, internal and external, clearance holes with the counterbores and countersinks of the standards, and the knurls of DIN 82; sections and projections that are regions again; STEP in and out.
• Meshes: STL, OBJ, PLY and 3MF read and written with their colours, cut into regions and fitted back to lines and arcs, and taken into booleans.
• Assemblies: named parts placed together, written to STEP and 3MF with their structure.
• Technical drawings: a drawing model with a layer table of colours, line types and line weights, dimensions, hatches, blocks and an ISO title block; plotted, printed to scale, set in TikZ and written to DXF.
• A viewer: Open CASCADE's own window, to turn a part, pick its edges, faces and solids, pick a coordinate system with the mouse, hide solids or show them through, set the view, and capture what it shows as a picture.

inst/+geom      outlines, curves and planar geometry, read and written as DXF
inst/+polymesh  STL, OBJ, PLY and 3MF meshes read, written and cut
inst/+draw      the drawing model, its backends, and drawings as DXF
inst/+solid     solids through Open CASCADE, STEP, and meshes for a slicer
inst/+model     assemblies of solids and meshes, and the viewer
src             compiled code: meshes, DXF, and the interface to Open CASCADE

+geom is the middle layer and depends on none of the others: solids are made from its regions and cut back into them, meshes are cut into them, and drawings are made of them. How each class becomes another is set out in the guide's Package layout.

DXF is read and written by compiled code that needs nothing but Octave: R2000 by default, R12 on request, and any ASCII file from R12 to R2018 read. A geom object keeps its coordinate system in the file, and a drawing its layer table, dimensions, hatches and blocks. What each class becomes in a file and back is set out in the guide's DXF and the classes.

Where the package follows a standard, the guide's Standards pages set out which edition, where each number comes from and how it is computed, and what the package decides where the standard leaves the choice open. Threads and tapped holes covers ISO 261, ISO 68-1, ISO 965-1 and ISO 2306, and the countersink of a tapped hole from IS 1369 (Part 3), prepared from DIN 76-1; Clearance holes, counterbores and countersinks covers ISO 273 and IS 3406, prepared from DIN 74; and Knurls covers DIN 82, read in IS 3403, prepared from it. Each is read in an Indian Standard that anyone can download free.

The guide has nineteen tutorials that build parts and drawings step by step. Every output and every picture on them is made by the code above it. New to Octave? Start with A brief Octave primer, the Octave the tutorials use.

1. A first part: a mounting plate from outline to STEP and STL.
2. Outlines: polylines, splines, paths and regions: the four classes every shape is drawn with.
3. Working with regions: booleans, offsets, fillets, hulls, arrays and text.
4. Coordinate systems: planes of their own, and features on the faces of a part.
5. Solids from regions: extrude, revolve, loft, sweep and coil.
6. Primitives, booleans and transforms: solids built the way OpenSCAD builds them, in colour.
7. Features: holes, pockets, fillets, chamfers and shells: a bearing block finished as a machinist would finish it.
8. Sections and projections: cuts and outlines of a solid, built from and drawn.
9. Technical drawings: layers, dimensions, hatches, blocks, a sheet, and paper, LaTeX and DXF.
10. Meshes: reading, writing, cutting and fitting meshes, and meshes in booleans.
11. Assemblies: parts placed together, saved to STEP and 3MF.
12. For OpenSCAD users: OpenSCAD's words in the package's, and a classic model rebuilt.
13. Surfaces through a grid: a ripple from meshgrid, as facets and as an exact surface made a solid.
14. Parts as functions: a bracket in a file of its own, made in any size.
15. Testing parts: %!test blocks that check a part's volume and fit, run with test.
16. Holes and threads: tapped holes and a threaded rod, and a bolt circle on a picked face.
17. Clearance holes, counterbores and countersinks: the holes a screw passes through, and the seats that sink its head.
18. Looking inside a model: solids hidden or shown through in the viewer, chosen by name.
19. Knurling: a knurled knob, the seven types of DIN 82, and its ends finished.

The scripts the pages are built from are in docs/guide/src.

Every function and class method is documented in texinfo, reachable from the Octave prompt with help. Use dot notation for namespaced functions and for the methods and properties of the classes:

help geom.offset
help draw.Drawing
help draw.Drawing.print
help solid.Shape.hole

The function reference, with every docstring and demo, is at https://pr0m1th3as.github.io/drafting/, and the guide with its tutorials at https://pr0m1th3as.github.io/drafting/guide/. The reference can also be built locally with the pkg-octave-doc package: with both packages installed and loaded, in any folder you can write to, run:

package_texi2html ("drafting")

ROADMAP.md sets out what is planned and why, ordered by what unblocks what. Just as usefully, it sets out what is deliberately out of scope: no CAM, no DWG, no solid-modelling kernel of its own, no constraint solver, each with the reason it was ruled out.

To install the latest release, you need Octave (>=11.1.0) installed on your system, and on Linux, FreeBSD and macOS the libraries set out below. Install it by typing:

pkg install drafting

You can automatically download and install the latest development version of the drafting package found here by typing:

pkg install "https://github.com/pr0m1th3as/drafting/archive/refs/heads/main.zip"

If you need to install a specific release, for example 0.2.0, type:

pkg install "https://github.com/pr0m1th3as/drafting/archive/refs/tags/release-0.2.0.tar.gz"

The package builds on Linux, FreeBSD, Windows and macOS. Everywhere it needs Open CASCADE 7.8 or later, 8.0 included, with its visualization libraries; what else it needs, and where Open CASCADE comes from, depends on the system:

• Linux and FreeBSD: Open CASCADE, the X11 headers and zlib at build time. The headers are looked for in /usr/local/include/opencascade and /usr/include/opencascade, and the libraries next to them. On Debian or Ubuntu, where the packaged version is 7.8 or later, install them before the package with:

  sudo apt install libocct-foundation-dev libocct-modeling-data-dev libocct-modeling-algorithms-dev libocct-data-exchange-dev libocct-visualization-dev libx11-dev zlib1g-dev

  The Makefile is GNU make's, so on FreeBSD install gmake and type setenv ("MAKE", "gmake") before pkg install.

• Windows: with GNU Octave 11.1.0 or 11.3.0 from octave.org, pkg install fetches a build of Open CASCADE made with Octave's own compiler and installs it with the package, so nothing else is needed; Open CASCADE already in Octave's mingw64 folder, or named by OCCT_INC, is used instead.

• macOS: install Octave and Open CASCADE with Homebrew, brew install octave opencascade, before pkg install; they are looked for in /opt/homebrew first. The viewer uses a window of macOS's own, so X11 is not needed.

If Open CASCADE is elsewhere, name its directories before installing, for example setenv ("OCCT_INC", "/opt/occt/include/opencascade") and setenv ("OCCT_LIB", "/opt/occt/lib"); on Linux and FreeBSD, X11_INC and X11_LIB do the same for X11. The package records where it found the libraries, so they need not be on the system's library path, and headers found outside /usr without their libraries beside them stop the build rather than link another version.

After installation, type:

• pkg load drafting to load the drafting package.
• news drafting to review all the user visible changes since last version.
• pkg test drafting to run its test suite and check that it works on your system.