2.2. Building in three dimensions

The other domain of anableps is building scenes in threedimensional space. Let’s begin with a simple example:

box b: .size 10 10 10 cm
save file3.png .width 300px

The one above is a minimal program that, however, actually works. It works because, as everywhere else in Anableps, it’s using clever defaults to make quick tests possible. However, in the example above, there are several steps in displaying the scene that have been taken implicitly. Let’s see how it works:

First, a box has been created in the current (default) scene (accessible through the scene variable). As no placement information has been set, it has been assumed to be at the origin, with its sides parallel to the principal planes.

Next, the function save() that saves a scene to a file is invoked. save() take several parameters to specify which scene to save, from which point of view (which camera), which kind of rendering, etc. but, if invoked bare as here, it defaults to the current scene (scene) and the default camera, which its a camera that just places itself in a point where everything gets into frame, pointing to the center-of-mass of the ensemble (see camera reference for the actual algorithm).

Same goes for the rendering procedure. There are many renderers available in Anableps (see [[renderers]] section) but by default, a simple BREP outline renderer is chosen.

Compare with a somewhat tailored script:

box b: .size 10 10 10 cm .place .center @ (10,10,10) .rotate 10 20 deg
camera c: .from 50 50 50 .target box.top.nw .aperture .3 .up 3 4 1
s = snapshot: .camera c  .renderer ray-trace
s.save: .file "file3.png" .width 300px

Here we have explicitely defined the camera position and the kind of rendered wanted.

In brief, in three dimensions, we have:

• An scene, where objects are added, and placed. Several scenes can be used at the same time. There is no relationship among them, until one is placed inside other.
• A camera that sets the place where from to get the snapshot.
• A renderer that produces a 2D image with the scene information.

We now proceed to explain the procedure with all the options. For a full reference see camera reference, anables renderers.

2.2.1. The Scene

Just the same as in two dimensions there is always a canvas onto which shapes are placed, in 3D, objects are placed in a scene. As with the canvas, there is always one default scene where everything is being placed (the scene global variable), but multiple scenes can be used, or the default changed:

cylinder c: .diameter 40inches .height 20mm
# gets placed in the default scene

However, a different scene could be set for some object, or accessory construction:

scene s2: # creates a new scene
cylinder d: .diameter 10mm .height 3mm .scene s2
scene s3:
scene = s3  # default scene will be s3 now.

Scenes be swapped and managed:

scene, sold = new scene, scene  # this swaps scenes

2.2.2. The bodies

Just the same as in 2D everything was a shape, 3D objects are called bodies, to distinguish them from shapes. Apart from that, they behave very much as shapes: they have attributes that should be set in order to create the scene.

Note

Note that in a piece of code, there is always a current scene and a current canvas defined. Operations target on one or the other, and usually is clear where goes each sentence. But there some cases in which a class name can refer both to a 2D entity or a 3D one. In those clashing cases, 3D bodies have a “3” after the classname**: examples:

* ``rectangle` is a 2D shape. ``rectangle3`` is a rectangle in 3D

Some examples:

• arrow3: an arrow in three dimensions
• segment3: a segment in the scene
• line3: a line in the scene
• point3: a point in the scene

2.2.2.1. Repertoire

There are hundreds of bodies available. The following is a selection. For the whole set, please go to the body reference

• basic shapes. brick, sphere, ellipsoid, cone, cylinder,
• flat geometry in 3d: triangle2, polygon2,
• other bodies: star,
• things:

2.2.2.2. Properties of bodies

asdfsafd

2.2.2.3. Composition of objects

As expected, new bodies can be made out of aggregations of bodies

2.2.2.3.1. New toponymics

con export

2.2.2.3.2. Access to details

con name.asdfasdf

2.2.2.4. Creation in code

asdf

2.2.2.5. configuration / stances

different configurations

2.2.3. Placement in 3D

We have alredy seen that when we create bodies, they are placed at the origin of the current scene by default. Alternatively, as happened in 2D, they can be placed in several ways:

• Using layouts for two dimensions and specifying the height for each one
• Using matings and constraints to place an object in relationship with others
• By hand, invoking the interactive() function and moving them to place.

When we want to place some object, we can give the constraints needed to do so After having resolved the constraints, when the placement instruction is done, those constraints disappear:

box b1:
set b1: top.nw @ (10,10,20)cm , top.sw @ (30,30,40) , .side *, .width = .height
b1: .top @ (10,10,20)  .top.width = 20  # alternative syntax?

In this example we are setting side to free values. Set commands allow placing the bodies _and_ changing additional parameters

• place: one-shot for placing objects
• set: one-shot for placing and modifying objects
• mate: places mates forever. If any of the two objects changes, the other will change too.

2.2.3.1. Matings

For simple placements, just a .place parameter allows specifying simple constraints:

box b: .size 20 20 20  .place .center @ (20 20 20)

For more complex placements, use the command place:

box b: .size 20 20 20
box c: .size 30 30 30
place c: .center @ 40 40 40
place b: .center @ c.south.center

Placement uses the same algorithm as the placement in 2D (see placement in 2D for reference)

There is a third way, in which we specify some rule that should be followed always:

mate box1.top.nw @ p1

This creates a mate, so the box will be moved, whenever p1 is moved

If I move p1, afterwards:

p1.moveto 20 20 20cm

What happens to the box depends of whether it has some free ( =*) parameter.

2.2.3.2. Layouts

They work just the same as in 2D, although the fact that only two dimensions are specified makes them less powerful. third coordinate (usually Z) must be specified:

layout l : <<<
>>

2.2.3.3. Interactive

2.2.4. Identities

Let’s say I create a box and an external point:

Point p1: .at 100 100 100cm
box b1: side 4cm

Afterwards, I type:

box1.top.nw = p1

This means that, for now on, top.nw will be p1. Whatever is happens to p1 it will affect to box1. Now, what happens to the box

1. gets moved
2. gets resized

If we want just place the box where is p1, we should use:

box1.top.nw.move .to p1

In this case, if we move p1, p1 and top.nw cease being in the same place

2.2.5. Silk layer

There is also a silk concept for 3D scenes. In this case, silk is a canvas that is overlaid to the 2D rendering of the scene. 2D objects can be placed on this layer. Silk layer is a bit special in that:

• As is a canvas, its overlaid onto the snapshot of the scene.
• Sizes of labels, lines, etc are given in units of the physical media where the snapshot is finally rendered.
• 3D coordinates of the scene can be used to place labels, rectangles, etc. They will be converted to the projected 2D into the silk canvas.
• In some cases, the underlying objects can cull partially some objects in the silk layer: think of an arrow pointing to an object behind some other from the current point of view

TODO: scene in which a label is partially hidden.

For drawing things on the silk layer of the scene, use the .silk3 parameter:

label : .target box.bottom.se  .text "label to corner" .silk3

The .silk3 parameter means that the object goes to that special canvas (the silk variable can be found as scene.silk) that will be rendered ..after.. the snapshot has been rendered.

2.2.6. Cameras and lighting

For any rendering of the scene, a camera must be present, be it the default one or one chosen by the user.

Cameras are 3Dobjects, like every other and, if displayed, they look like a tiny (2cm@silk big) cinema cameras. of course, they are not usually displayed because they have its field .hidden set to true by default. All the cameras have the tag @camera that allows treating them as a block (for example to display/hide purposes):

set @camera.hidden false  # makes all the cameras in the scene visible

See [[camera reference]] for a full reference and further instructions about how to use the cameras.

In the same way, most renderers (except the most abstract ones) need light information to render a picture. Lights are like cameras: they are placed in the scene as regular objects, but they will not be displayed, unless explicitely told to do so, again by changing the .hidden attribute of the light, or using the tag @lights. Lights look like small bulbs

(dibujo con lights)

There are several kind of lights:

ambient:xxx directional:yyy point:zzz area:ccc

Furthermore, lights can be customized to shine only on some objects using .exclude and .include fields, and can be switched on and off independently for objects or groups. See [[lighting reference]] for further details:

box b: .size 20 30 30
box c: .size 20 30 40
place b @besides c
light l1: .from 10 10 10 .target 0 0 0 .intensity 500Cd .exclude c
light.ambient l2:
# box c gets only l2

Finally, as any other object, cameras, can be moved around, and this is fundamental when creating movies. this example below is but the tinniest example. For the full range of options and creating movies, see the [[movies]] section:

Box b: .size 20 30 40 .place .center @ origins
camera c: .pos traveling(.from 10 10 10 .to 20 20 20 .t_start 0.0 .t_end 20.0 ) .target b.center
movie m: .t_range 0 20 s .save movie2.mp4

2.2.7. Overview of objects and operators

Here is a non-exhaustive list of bodies available for creating scenes. New bodies can be created using the language (see [[creating bodies]]). Try and experiment with them.

kjhj<body.ellipsoid2>

go to box

2.2.7.1. Objects

Geometric:go to box , cube, cylinder, cone, .cavalieri, ellipse, tube, cable Creatures:person, horse, dog, Nature:mountains, river, houses, walls,

2.2.7.2. Operators

Operators are functions that operate on bodies.

2.2.7.3. object libraries

Hundreds of other objects are stored under namespaces, forming a library. Here is a layout of the available library objects.

2.2.7.3.1. creatures

A library full of creatures to place into your scenes:

• creature.human:
• creature.dog:
• creature.horse:
• creature.lion:

Some examples:

countryside c: .height 20 .trees
creature.human bob: .place

2.2.7.3.2. things

A library full of things