Render line drawings from 3D meshes, suitable for plotters

ApparentRidges contains an implementation of the paper Apparent Ridges for Line Drawing by Judd et al. 2007. It also includes a software raycaster to cull occluded lines, a custom algorithm to connect ridge segments into continous polylines suitable for plotters, as well as utilities for manipulating meshes and generating depth/normal/curvature maps.

Written in Haxe and transcompiled for your favourite programming language. Many parts of it are based on the awesome RTSC viewer, which contains a C++ version of the Apparent Ridges algorithm, as well as Trimesh2, the mesh library used by RTSC.

The library is written in the Haxe programming language, and is transpiled to C/C++, JavaScript, Java, Python and Lua ports, all of which is available in this repo, along with code examples in these languages. Processing and OpenFrameworks examples are also included. See Navigation section for details.

The library can be further transpiled to C#, PHP, SWF(Flash), JVM bytecode or Neko (a Haxe VM) but these will not be maintained in this repo.

A commandline interface (CLI) is also included for convenience. Two functionally equivalent (but performance-wise drastically different) versions exist: One is compiled from C++, one is a Python script.

A list of samples generated by this algorithm for the standard test meshes (bunny, dragon, etc.) can be found in the samples/ folder. They're downloaded from the Stanford collection and Keenan Crane's collection, and modified with Meshlab to a reasonable amount of triangles (50k-500k) in OBJ format. The modified version of the models used by this repo can be downloaded here. Some of the examples assume these files are in the testdata/ folder in the repo.

• Eats OBJ and spits SVG by default -- but custom loaders and writers can be plugged in due to modular design. The polylines can also be directly grabbed for drawing onto the screen for graphic applications.
• Different modes of output: Disconnected ridge segments (directly from the standard algorithm), connected polylines (via post-processing, suitable for plotters), or gradated rendering showing ridge strength along the strokes.
• Also capable of generating raster images including depth map, normal shading, curvature map, lambertian shading, ambient occusion. Includes a PPM format writer for easy preview.
• Zero dependencies (except for C/C++ ports which might require hashlink/hxcpp).

See Programming API and Commandline API sections for details.

More Detail about the items might be found in each folder README or as code comments.

• Haxe source code in apparentridges/ApparentRidges.hx
• CLI source code

• JavaScript version of the library
• JavaScript interactive demo
• Render the sample meshes with JavaScript
• Java version of the library
• A .jar file for grabbing
• Processing library
• Processing example
• Python version of the library
• Python commandline interface
• Python example
• Lua version of the library
• Lua example
• C++ version of the library
• C++ commandline interface
• C version of the library
• C example
• OpenFrameworks example

• samples/ folder containing reference renderings from this library.

Compiling is not neccessary to use the library, except for C/C++. This section is for people who'd like to modify / contribute to the source code.

The included Makefile automates compilation and testing. To compile for a library in particular target language (e.g. JavaScript), use

make js

To compile libraries in all languages, use

make libs

To compile the commandline interface, use

make clis

To compile the commandline interface in a particular language (e.g. Python), use

make cli-py

To run tests the sample meshes, use

make tests

To test a particular mesh (e.g. the bunny), use

make test-bunny

To do all of the above all at once (takes quite a while!), use

make all

usage:   apparentridges [options] [.obj files...]

option        default       description

--thresh      0.1           apparent ridge threshold
                            smaller => more detailed, larger => cleaner

--transform   auto()        place the model before rendering
                            (multiple commands are left-multiplied in order)
                            available commands:
                            focal(100) translate(1,2,3) scale(4,4,4)
                            rotateX(1) rotateY(2) rotateZ(3);
                            matrix(11,12,13,14,21,22,...,43,44)
                            rotation angles are in degrees
                            use auto() or auto(zFactor,fFactor) for automatic
                            placement. (cam is fixed at (0,0,0) pointing at +Z,
                            focal() needs to be specified for manual placement)

--output, -o  out-hher.svg  output filename
                            (randomly generated if not specified)

--verbose     1             verbosity: 0 => errors only, 1 => logs

--cull        true          don't draw occluded faces
                            options: true/false/custom float value (e.g. 1.5)
                            the float being a multiplier to the 'epsilon',
                            allowing ridges just barely occluded to show up

--width, -w   800           width of output image

--height, -h  800           height of output image

--mode        gradients     visualization technique, options:
                            vertices, edges, 
                            lines (disconnected ridge segments),
                            polylines (connected ridges via post-proc),
                            gradients (nice render showing ridge strength),
                            pixels (raster out: depth, norm., curv. maps)

Please also checkout the full API Documentation. This section covers a typical usage example.

Shown below is the JavaScript (node.js) API. API for ther languages work similarly, see respective examples listed in Naviagtion section above for details.

// import the apparent ridges library
const {apparentridges} = require("./apparentridges");

// alias for lazy people
const AR = apparentridges;

// for loading files from disk
const fs = require('fs');

// load the .OBJ file: The head of Max Planck
let objstr = fs.readFileSync("./testdata/planck_100K.obj").toString();
let mesh = AR.OBJParser.fromString(objstr);

// alternatively, you can construct the mesh yourself, e.g.
// let mesh = new AR.Mesh();
// mesh.vertices.push([0.1,0.2,0.3]);
// mesh.faces.push([0,1,2]);

// create a renderer
// the renderer uses a simple pinhole camera model
// you can replace it with your own exquisite renderers if desired
let render = new AR.Render(mesh,800,800);

// rotate the model, so the Planck is not looking at the ground
render.transform(AR.Util.matRotx(-Math.PI*0.5));
render.transform(AR.Util.matRoty(Math.PI*0.2));
render.transform(AR.Util.matRotx(-0.3));

// autopmatically puts the model at a nice position for viewing
// the two parameters are multipliers to the z-distance and focal length.
// leave out to let the algorithm do the thinking.
render.autoPlace(3,2.4);

// render the apparent ridges.
// First argument is threshold (smaller->more detailed, larger->cleaner)
// Second argument controls the culling. For any negative values, there'll
// be no occlusion at all, allowing hidden lines to be seen. For non-negative
// values, this is used as the tolerance epsilon: larger values allows
// lines that're just blocked by a tiny bit to be seen.
render.apparentRidges(0.25,10);

// connect the ridge segments to continous polylines (optional)
render.buildPolylines();

// Use the SVG writer to write out the image.
// other modes: SVGWriter.lines, SVGWriter.gradients
let rstr = AR.SVGWriter.polylines(render);
fs.writeFileSync("output/planck.svg",rstr);

// we can also generate a curvature map (among many other maps) for the model
let pix = AR.PixelMap.curvature(render,true);
// Use a builtin PPM format writer for preview
// last two parameters are normalization range
let pstr = AR.PixelMap.toPPMString(pix,render.width,render.height,-0.5,0.5);
fs.writeFileSync("output/planck-curv.ppm",pstr);