Graphics.OpenSCAD

The Graphics.OpenSCAD module provides abstract data types for creating OpenSCAD model definitions calls, along with a function to render it as a string, and some utilities. The primary goal is that the output should always be valid OpenSCAD. If you manage to generate OpenSCAD source that causes OpenSCAD to complain, please open an issue.

Standard usage is to have a main function that looks like:

main = draw $ Solid

and then set your IDE's compile command to use runhaskell or equivalent to run your code and send the output to a .scad file. Open that file in OpenSCAD, and set it to automatically reload if the file changes. Recompiling your program will cause the model to be loaded and displayed by OpenSCAD.

The type constructors are generally not exported, with functions being exported in their stead. This allows extra checking to be done on those that need it. It also provides consistency, as otherwise you'd have to remember whether box is a constructor or a convenience function, etc.

Because of this, the constructors are not documented, the exported functions are. The documentation is generally just the corresponding OpenSCAD function name, along with the names of the arguments from the OpenSCAD documentation. If no OpenSCAD function name is given, then it's the same as the OpenSCAD function. You should check the OpenSCAD documentation for usage information.

Basic data types

data Solid

A Solid is a solid object in OpenSCAD. Since we don't have optional or named objects, some constructors appear twice to allow two different variants to be used. And of course, they all have all their arguments.

Instances

Show Solid

data Shape

A Shape is a two-dimensional object. They are a separate type so that Haskell can type check that we aren't using a 2d operation on a 3d shape, or vice versa. Unfortunately, this means the dynamically typed functions that accept either - and possibly generate either - need to have two versions of those functions. I believe the 2d creation functions are more common for 2d objects, but the 3d transformation functions are more common. Hence the 2d creation functions (which have the names of 2d objects like circle, square, etc.) that create Solids have 3d appended, but the 3d version of transformations that have both 2d and 3d versions have 3d appended.

Instances

Show Shape

data Facet

A Facet is used to set one of the special variables that control the mesh used during generation of circular objects. They appear as arguments to various constructors, as well as in the var function to set them for the argument objects.

Instances

Show Facet

Type aliases to save typing

type Vector = (Float, Float, Float)

Vector is used where OpenSCAD expects an OpenSCAD vector of length 3.

type Point = (Float, Float)

Point is used where OpenSCAD expects an OpenSCAD vector of length 3.

Rendering functions

render :: Solid -> String

render does all the real work. It will walk the AST for a Solid, returning an OpenSCAD program in a String.

draw :: Solid -> IO ()

draw is a convenience function to write the rendered Solid to standard output.

Constructors

Solids

sphere :: Float -> Facet -> Solid

Create a sphere with sphere radius 'Facet'.

box :: Float -> Float -> Float -> Solid

Create a box with cube x-size y-size z-size

cube :: Float -> Solid

A convenience function for creating a cube as a box with all sides the same length.

cylinder :: Float -> Float -> Facet -> Solid

Create a cylinder with cylinder radius height 'Facet'.

obCylinder :: Float -> Float -> Float -> Facet -> Solid

Create an oblique cylinder with cylinder /radius1 height radius2 Facet/

rectangle3d :: Float -> Float -> Solid

Create a rectangular Solid with rectangle x-size y-size.

square3d :: Float -> Solid

square3d is a rectangle3d with both sides the same size.

circle3d :: Float -> Facet -> Solid

Create a circular Solid with circle radius Facet.

import3d :: FilePath -> Solid

__UNTESTED__ import3d is import filename, where filename is an stl file. It's 3d because import is a key word.

linearExtrude

Arguments

:: Float

height

-> Float

twist

-> Point

scale

-> Int

slices

-> Int

convexity

-> Facet

-> Shape

to extrude

-> Solid

Extrude a Shape along a line with linear_extrude.

rotateExtrude :: Int -> Facet -> Shape -> Solid

Rotate a Shape around the origin with rotate_extrude convexity 'Facet' 'Shape'

Shapes

rectangle :: Float -> Float -> Shape

Create a rectangular Shape with rectangle x-size y-size.

square :: Float -> Shape

square is a rectangle with both sides the same size.

circle :: Float -> Facet -> Shape

Create a circular Shape with circle radius Facet.

import2d :: FilePath -> Shape

__UNTESTED__ import2d is import filename, where filename is an image or other 2d object.

projection :: Bool -> Solid -> Shape

Project a Solid into a Shape with projection cut 'Solid'.

Combinations of Solids

union :: [Solid] -> Solid

Create the union of a list of Solids.

intersection :: [Solid] -> Solid

Create the intersection of a list of Solids.

difference :: Solid -> Solid -> Solid

The difference between two Solids.

minkowski :: [Solid] -> Solid

The Minkowski sum of a list of Solids.

hull :: [Solid] -> Solid

The convex hull of a list of Solids.

Transformations

Solids

scale :: Vector -> Solid -> Solid

Scale a Solid, specifying the scale factor for each axis.

resize :: Vector -> Solid -> Solid

__UNTESTED__ Resize a Solid to occupy the given dimensions.

rotate :: Vector -> Solid -> Solid

Rotate a Solid by different amounts around each of the three axis.

translate :: Vector -> Solid -> Solid

Translate a Solid along a Vector.

mirror :: Vector -> Solid -> Solid

Mirror a Solid across a plane intersecting the origin.

multMatrix :: Transform -> Solid -> Solid

Transform a Solid with a Transform matrix.

color :: Colour Float -> Solid -> Solid

Render a Solid in a specific color. This doesn't us the OpenSCAD color model, but instead uses the Colour model. The OpenSCAD module rexports Names so you can conveniently say color red 'Solid'.

transparent :: AlphaColour Float -> Solid -> Solid

Render a Solid in a transparent color. This uses the AphaColour color model.

up :: Float -> Solid -> Solid

A translate that just goes up, since those seem to be common.

projection3d :: Bool -> Solid -> Solid

Project a Solid to a thin Solid with projection cut 'Solid'.

Shapes

scale2d :: Point -> Shape -> Shape

scale2d is scale for Shapes.

resize2d :: Point -> Shape -> Shape

resize2d is resize for Shapes.

rotate2d :: Point -> Shape -> Shape

rotate2d is rotate for Shapes.

translate2d :: Point -> Shape -> Shape

translate2d is translate for Shapes.

mirror2d :: Point -> Shape -> Shape

mirror2d is mirror for Shapes.

General convenience functions

diam :: Float -> Float

Use diam to turn a diameter into a radius for circles, spheres, etc.

Convenience functions for Facets.

var :: Facet -> [Solid] -> Solid

var uses assign to set a special variable for the Solids.

fn :: Int -> Facet

fn is used to set the $fn variable in a Facet or var.

fs :: Float -> Facet

fs is used to set the $fs variable in a Facet or var.

fa :: Float -> Facet

fa is used to set the $fa variable in a Facet or var.

def :: Facet

def is used where a Facet is needed but we don't want to change any of the values.