W Cx Cy Cz
H Fx Fy Fz


Fig3

A simple drawing tool for the programmatic generation of 3D figures, on the basis of the Three.js library and standard Javascript code. Emphasis is on schematics and line drawings with partly transparent solids, of modest complexity, and accompanied by annotations and labels, as seen frequently in more technical scientific articles. Images are exported in vector format.

Figures are programmed in Javascript. You might wish to operate in your favorite text editor and paste the code into the Fig3 edit window for rendering and further fine-tuning. Most features of the Three.js library, with extensive documentation, are available. Fig3 itself provides some functions as shortcuts to the sometimes lengthy Three.js statements. See the following pages for a list of these built-in functions, and for a series of examples.

Drawings can be exported to vector image files with extension .svg (Scalable Vector Graphics, SVG). Conversion to other formats, preferably also vector-capable, such as .pdf, for inclusion in a LaTeX document is possible e.g. through Inkscape, also as a command-line option. Note that .eps does not support transparent elements, here the conversion generates raster (bitmapped) images.

Upon opening the Fig3-page, the Three.js-modules are downloaded from the server where also the Fig3 website resides. Your code is then interpreted and rendered entirely locally on your machine, by your web browser. None of your input data is being sent over your internet connection (unless things happen that are beyond control of the Fig3-scripts, that is).

Fig3-figures can be saved and re-opened as files with default extension .f3. Besides the figure-generating code, these text files include the data on view options (figure size, camera position, focus) in JSON format. Note that, just as any other piece of computer code, these files must be considered as potentially unsafe, if obtained from an — possibly obscure — external source. Fig3 internally uses the Javascript-eval function to interpret the code, to render the figure.

Manfred Hammer, Paderborn University, Paderborn, Germany
manfred.hammer@uni-paderborn.de, © 2023 MH
SiIO.eu
Coding

See the Three.js documentation first.

Fig3 provides the container Scene (capitalization) of type THREE.Scene. Objects need to be added to this scene to become visible, and need to be given a renderOrder, such that transparency is handled properly. The scene is then displayed by an instance of THREE.SVGRenderer. Textures, shadows, and shading are not supported by this workflow.

The "plate" establishes a plane x ∈ [-5, 5], z ∈ [-5, 5] at y=0; coordinate directions are indicated. The scene is to be constructed using those coordinates, typically in some region around the origin. The plate renders with order 0; objects with higher renderOrder are drawn later.

Note that the figure code is interpreted in the same script-environment that also handles the operation of the Fig3 web-page. To avoid a clash of names, variables and functions in the figure code should preferably not start with an underscore _.

Fig3 includes the following wrappers for some elementary objects. Mostly, these functions generate the drawable objects in some default position. For further positioning, the many methods of the general THREE.Object3D are available. Among these are rotateX, rotateY, rotateZ for rotating, and translateX, translateY, translateZ for translating the object, in both cases with respect to its local axes. Objects can then be added conveniently to the Fig3-scene with the Draw -function.

  • Rad(d)  ⟶ Number
    Transform rotation angle d from degrees to radians, as required for the rotateX, rotateY, rotateZ-functions.
  • P3(x, y, z)  ⟶ THREE.Vector3
    Representation of a position / vector in 3D with coordinates x, y, z.
  • Linestyle(c, w)  ⟶ THREE.LineBasicMaterial
    Determines the color c and width w of lines.
  • Line(p, ls)  ⟶ THREE.Line
    A line along the P3s in array p with linesstyle ls.
  • Ellipse(rx, ry, a0, a1, n, ls)  ⟶ THREE.Line
    An angular segment of an elliptic curve in 2D, with half-axes rx and ry along directions x and y, drawn from angle a0 to a1, discretized by n points, with linestyle ls.
  • Curve(p, n, ls)  ⟶ THREE.Line
    A smooth curve through the P3s in p, interpolated with n steps, drawn with linestyle ls.
  • Arrow(p0, p1, ls, l, w)  ⟶ THREE.ArrowHelper
    An arrow, consisting of a line between P3s p0 (start) to p1 (end), drawn with linestyle ls, ending in an arrowhead of length l and width w (values relative to default dimensions).
  • Medium(c, o)  ⟶ THREE.MeshBasicMaterial
    A transparent medium of color c, opacity o.
  • Box(wx, wy, wz, m)  ⟶ THREE.Mesh
    A rectangular box of dimensions wx, wy, wz along the x, y, z directions, centered at the origin, made of material m.
  • Polyeder(p, m)  ⟶ THREE.Mesh
    The polyeder constructed as the convex hull spanned by the P3s in array p, at least 4 points are required.
  • P2(x, y, z)  ⟶ THREE.Vector2
    Representation of position / vector in 2D with coordinates x, y.
  • Shape(p)  ⟶ THREE.Shape
    A shape in 2D, defined by the - at least three - P2s in array p.
  • Ring(r0, r1, a0, a1, n)  ⟶ THREE.Shape
    Angular segment of a ring in 2D, with inner radius r0 and outer radius r1, extending from from angle a0 to a1 [rad], discretized in n angular segments.
  • Extruded(s, l, m)  ⟶ THREE.Mesh
    An extruded object, formed by translating the shape s along z over the distance l, filled with material m.
  • Edges(o, ls)  ⟶ THREE.LineSegments
    The edges extracted from the THREE.Mesh-object o, to be shown with Linestyle ls.
  • Draw(b, o)
    Add the object b to the scene with renderOrder o; choose increasing values o the closer the objects get to the camera.
  • Label(t, p, a, c, s)
    Add the text t as a label at P3 p of color c and size s [px], anchor a: a two-character string, first one of "t", "m", "b" for top, middle, or bottom vertical alignment, then one of "l", "c", "r" for left, center, or right horizontal alignment at point p. The actual position of the labels in the 2-D image depends on the rotation/camera position of the scene, determined by their anchor points. The labels remain legible, irrespective of the orientation of the scene.
  • Text(t, x, y, a, c, s)
    Add the text t at the image coordinates x, y as a label of color c and size s [px], anchor a: a two-character string, first one of "t", "m", "b" for top, middle, or bottom vertical alignment, then one of "l", "c", "r" for left, center, or right horizontal alignment at position (x, y). These texts are meant as labels for the final image, they do not change their positions when rotating the camera, or with a change of focus distance.

Note that Label and Text add the labels directly to the figure. These labels are not part of the scene, but become part of the SVG-image in separate groups. They appear in front of all other objects.

Texts and Labels accept standard HTML character entities: &alpha; &beta; &gamma; &delta; ⟶ α β γ δ. The HTML-tags <sub></sub> and <sup></sup> can be used for formatting subscripts and superscripts, respectively: |E<sub>y</sub>|<sup>2</sub> ⟶ |Ey|2.

Example

Lineup of some Fig3 elementary objects, use of the wrapper functions

Example

Pacman in 3D

Example

Geometry of a dielectric optical rib waveguide

Example

A dielectric step for semi-guided optical waves, schematically

Example

An integrated optical microresonator with racetrack-shaped cavity

<×>
Fig3