An introduction to Sketch 3D for PGF and TikZ users

• Published 2007-02-25 (4 years, 11 months ago)
• Updated 2007-03-25 (4 years, 10 months ago)

More then a year ago I wrote enthusiastically about Sketch 3D, a tool for creating simple 3D scenes for use with (La)TeX. Originally it generated PSTricks code, but recently the author added support for PGF and TikZ. In this notebook entry I will give a brief introduction to this great tool. Note that you have to read the Sketch manual to actually learn Sketch. I will only cover aspects specific to PGF and TikZ.

Contents

• An introductory example
• How it works
• PGF/TikZ options
  • Custom styles
• Specials
• Tips and tricks
• Examples

An introductory example

I'll start with this simple pyramid scene:

To draw the pyramid I have to open a text editor and write the following code:

def O (0,0,0) % origo
def J [0,1,0] % rotation axis
def dx 2.3
def dy 2.5
def dz dx

def axes {
    % draw the axes
    def ax (dx,0,0)
    def ay (0,dy,0)
    def az (0,0,dz)
    line[arrows=<->,line width=.4pt](ax)(O)(ay)
    line[arrows=->,line width=.4pt](O)(az)
    % annote axes
    special |\path #1 node[left] {$z$}
                   #2 node[below] {$x$}
                   #3 node[above] {$y$};|(az)(ax)(ay)
}

def pyramid {
    def p0 (0,2)
    def p1 (1.5,0)
    def N 4
    def seg_rot rotate(360 / N, [J])
    % draw the pyramid by rotating a line about the J axis
    sweep[cull=false,fill=blue!20]
        { N, [[seg_rot]] } line(p0)(p1)
    {axes}
}

put { view((10,4,2)) } {pyramid}

global { language tikz }

To get the final drawing I have to process the above code with Sketch and TeX. Saving the code as pyramid.sk, I can generate the drawing with:

> sketch -T pyramid.sk > pyramid.tex
> pdflatex pyramid.tex

The first command creates the TikZ code. The -T option puts the code inside a predefined template, making it a standalone document. Without the option, Sketch will only output the drawing code.

A more interesting result is achieved by making the pyramid faces transparent and adding a red floor to the pyramid:

sweep[fill=red!20] { N<>, [[seg_rot]] }
    line[cull=false,fill=blue!20,fill opacity=0.5](p0)(p1)

The above example shows two of the major benefits of using PGF and TikZ with Sketch:

• The output can be compiled directly with pdfTeX
• Support for transparency

How it works

Sketch is a command line tool written by Eugene Ressler. It is written in standard C and is easily built on any platform with a C compiler. A binary is provided for Windows users.

Sketch's job is to process 3D scenes, make a 2D projection and generate a list of corresponding TikZ or PSTricks commands. Sketch accepts a small domain-specific language, designed for creating 3D scenes. With Sketch you can easily do things like affine arithmetics, transformations, sweeps and extrusions. Operations that are very hard or impossible to do with TeX.

A crucial part of Sketch is the projection of 3D objects to 2D. The classic depth sort algorithm (also known as painter's algorithm) is used to determine which polygons are shown . The algorithm also involves splitting overlapping polygons and it is useful to understand what this means in practice. I'll illustrate this with the following example of two intersecting polygons.

def scene{
    polygon[fill=red!20,draw=red]
        (0,0,1)(1,0,0)(0,1,0)
    put {rotate(25)} {polygon[fill=blue!20,draw=blue]
        (0,0,1)(1,0,0)(0,1,0)}
}

put { scale(2) then view((5,4,8)) } {scene}
global { language tikz }

The result is two intersecting polygons.

The generated code looks like this:

\filldraw[fill=red!20,draw=none](-.976,-.61)--(1.561,-.381)--(.608,.887)--cycle;
\draw[draw=red](-.976,-.61)--(1.561,-.381)--(.608,.887);
\filldraw[fill=blue!20,draw=blue](-.976,-.61)--(1.415,.371)--(-.66,1.697)--cycle;
\filldraw[fill=red!20,draw=none](-.976,-.61)--(.608,.887)--(0,1.695)--cycle;
\draw[draw=red](.608,.887)--(0,1.695)--(-.976,-.61);

To draw the figure, five different paths are drawn:

Note that the red triangle is split into two different polygons and two line segments, while the blue triangle is drawn using a single filldraw operation. This is the depth sort and polygon splitting in action.

PGF/TikZ options

Stroke and fill parameters are set using the well known option syntax:

line[arrows=<->,draw=red,line width=ultra thick](0,0,0)(1,1,1)
polygon[fill=lightgray,style=semitransparent](0,0,1)(1,0,0)(0,1,0)

From the example in the previous section, it is evidently that Sketch needs to know the difference between fill and stroke parameters. The PGF/TikZ parameters recognized by Sketch are listed in the TikZ/PGF options section of the manual.

Custom styles

TikZ makes it easy to mix stroke and fill parameters in a style definition. This makes it a bit difficult for Sketch. If you want to use custom styles, you have to use the fill style and line style options. This way Sketch knows which styles to copy when doing polygon and line splitting.

line[arrows=<->,line style=mylinestyle](0,0,0)(1,1,1)
polygon[fill style=myfillstyle](0,0,1)(1,0,0)(0,1,0)

It is up to you not to mix fill and stroke parameters. Mixing them may give some weird results.

Specials

Sketch allows you to embed raw TeX and PGF/TikZ code using special objects. This way you can easily annotate you drawings. The formal syntax is

special |raw_text|[lay=lay_value] point_list

where || can be any character. The points specified in point_list are available for use in raw_text, transformed to two dimensional coordinates. An example will hopefully make things clearer:

% Vector cross product
def O (0,0,0) % origin
def theta 60 % angle between U and V
def U 2*[1,0,0]
def V rotate(theta)*[U]
% Define styles
% The use of the [lay=under] option forces the code to be outputted
% at the beginning of the generated code. The default behavior is to
% output special at the end.
special |\tikzstyle{vector}=[-latex',very thick]
            \tikzstyle{angle}=[->,shorten >=1pt]|[lay=under]


def scene {
    def u (O)+[U]
    def v (O)+[V]
    def w (O)+[U]*[V]
    line[line style=vector] (O)(u)
    line[line style=vector] (O)(v)
    line[line style=vector] (O)(w)
    special |\path #1 node[below] {$\vec{u}$}
                   #2 node[below] {$\vec{v}$}
                   #3 node[above] {$\vec{u}\times\vec{v}$};|(u)(v)(w)
    % Annotate theta angle. Sketch currently does not support
    % curves. Use a curve path instead, with appropriate computed
    % startpoint, midpoint and endpoint.
    def s (O) + 0.5*[U]
    def m rotate(theta/2)*(s)
    def e rotate(theta)*(s)
    special |\draw[angle] #1..controls #2.. node[midway,below] {$\theta$}#3;|
        (s)(m)(e)
}

put { view((2,0.5,2),(O),[0,0,1]) } {scene}
global { language tikz }

The special command is really powerful, and my favourite Sketch feature.

Tips and tricks

Some random tips and tricks. Will probably be moved to a separate notebook entry.

Read the manual carefully

The manual is well written with many excellent examples. You save yourself from some frustration by reading the manual carefully.

Faces with equal depth are drawn arbitrary

The depth sort algorithm gets into trouble when faces have the same depth. A workaround is to offset one of the faces with a very small value. The offset is too small to be visible, but it will affect in which order the faces are drawn. Example:

def ee 0.000001
polygon[fill=red] (0.5,0,ee)(0,0.5,ee)(-0.5,0,ee)
polygon[fill=blue] (1,0,0)(0,1,0)(-1,0,0)

Here's another example:

def ee 0.000001
def jR 1.5/2
def jR_inner 0.5/2
def jH 2/2
def joint put{rotate(-15,[1,0,0])} {
    def n 20
    sweep[fill=blue!20, cull=false, draw=gray]{n<>, rotate(360/n,[0,1,0])}
        line[draw=gray,fill opacity=0.8,cull=false,fill=blue!20]
            (jR,-jH/2)(jR,jH/2)
    sweep[fill=darkgray, cull=false]{n<>, rotate(360/n,[0,1,0])}
        line(jR_inner,-jH/2-ee)(jR_inner,jH/2+ee)
}

{joint}
global { language tikz }

The left cylinder is drawn without the small offset ee. In this case the depth sort algorithm hides the inner cylinder. The result may be different if another view angle is chosen. Using a small offset for the inner cylinder solves this problem.

Document templates

Sketch's default behaviour is to only output drawing code. To compile the code you'll need some boiling plate code. Sketch ships with a default template which you activate with the -T option. You can easily create your own template which you specify with the -t filename option. Sketch will look in the template for the %%SKETCH_OUTPUT%% string and replace it with the code needed to draw the scene. Example template:

\documentclass{article}
\usepackage[x11names,rgb]{xcolor}
\usepackage{tikz}
\usetikzlibrary{snakes,arrows,shapes,backgrounds}
\usepackage{amsmath}

% Use preview.sty to crop the page
\usepackage[active,tightpage]{preview}
\PreviewEnvironment{tikzpicture}
\setlength\PreviewBorder{2pt}%

\begin{document}
%%SKETCH_OUTPUT%%
\end{document}

Report bugs and feature requests to the author

Sketch's TikZ support is new and there are probably bugs. Please report any issues to the author of Sketch. Remember that feedback from users is motivating.

Experiment with the view angle

Finding the right view angle often requires some trial and error.

Specials are affected by the view angle

Changing the view angle also changes the position of specials. You should therefore wait with fine tuning until you have found an view angle you are satisfied with.

Examples

Below is a small collection of different drawings made with Sketch. Click on them to see the source code. The truncated cone example is from the Sketch manual. Note that some of the examples were made while I started to use Sketch, so the code may not be of the best quality.