Almost everything you do with HoloDraw will consist of converting data to or from the HoloDraw format. This file format is intended to let you describe one object per line of data in a file, as compared with VRML which may use 10 to 30 lines to describe a single object. For example, suppose you want to put the caption Hello, World! at coordinates 1 2 3 in your image:
| HoloDraw | VRML 1 | VRML 2 |
|---|---|---|
text2:1 2 3,Hello, World! |
Separator {
BaseColor {
rgb [ 0.8 0.8 0.8 ]
}
Font {
name "Times-Roman"
size 12
}
Transform {
translation 1 2 3
}
Text2 {
string "Hello, World!"
justification LEFT
}
}
|
Transform {
translation 1 2 3
children [
Billboard {
axisOfRotation 0 0 0
children [
Shape {
appearance Appearance {
material Material {
diffuseColor 0 0 0
ambientIntensity 0.0
shininess 0.0
emissiveColor 0.8 0.8 0.8
}
}
geometry Text {
fontStyle FontStyle {
family [ "Times-Roman", "PLAIN" ]
justify "BEGIN"
size 1
style "PLAIN"
}
string "Hello, World!"
}
}
]
}
]
}
|
The goal of the HoloDraw format is to make it possible to describe an object in a one-line instruction (e.g. draw a line from point A to point B) and to set defaults that apply to all subsequent objects (e.g. color red).
You can have one "phrase" per line, or multiple "phrases" separated by semicolons. A phrase describing an object has a colon, such as "polygon:1 2 3,4 5 6,1 3 5". This immediately causes the object to be output with default attributes such as color. Or a phrase can set a value with an equal sign, such as "color=0.8 0.6 0.4". When a phrase changes a value it applies to all subsequent instructions. This might not be what some would expect, since the color for an object may be specified somewhere far away from the object itself. (In fact, if you cat several draw files together, you could even have a color instruction in one file affecting the colors of unrelated objects in subsequent files. Horrors!) However, this makes it possible to have much more compact files as opposed to specifying the same color 1000 times for a collection of 1000 points.
| HoloDraw sample | What it does |
|---|---|
| color=1 0 0 | Set color to Red for all subsequent objects (until changed again). The "1 0 0" sets Red, Green and Blue values on a scale of 0 (dark) to 1 (color fully on). |
| linewidth=3 | Sets all subsequent lines to 3 pixels wide. (Note: Works for VRML 1 output only. Line width is not supported by the VRML 2 language specifications.) |
| line:0 0 0,1 2 3 | Draws a line from point 0 0 0 to point 1 2 3 with color Red and linewidth 3 (from the preceeding settings). |
| line:0 0 0,1 2 3,4 5 6,7 8 9 | A line can have multiple segments. The whole line will be drawn in the same color. If you want to change color part way along the line, you have to create two separate lines. |
| point:0 0 0,1 2 3,4 5 6,7 8 9 | Instead of drawing a line connecting the specified points, this merely plots the points with nothing between them. This can be useful when you have hundreds or thousands of data points and you want to see their overall shape or structure. (You wouldn't have to put all 1000 points on the same line; in fact, things tend to bog down if you do.) |
| color=0 0 1;point:2 2 2,2 2 5 | An example of two phrases on one line, separated by a semicolon. This creates two points in blue, regardless of any previous color settings. However, subsequent objects will also be blue unless you change the color again. |
| polygon:0 0 0,0 3 0,3 0 0 | Draws a triangle using the current color and transparency (if supported by your choice of VRML version and viewer). You can have polygons with more than 3 points, but if you do, it is your responsibility to make sure all the points are in the same plane. |
| fontname=Times-Roman;fontheight=12;fontjust=CENTER | Set some text attributes. |
| text2:9 8 7,whatever you want to say here | Puts a 2D caption (letters face the viewer) at coordinates 9 8 7 using the currently established text attributes. |
Here is a complete list of values that can be set, using the equal sign:
| Keyword | Values accepted | Example | Notes |
|---|---|---|---|
| color | 0.0 to 1.0 for each of Red, Green and Blue | color=0.0 0.5 1.0 | Turns Red off, Green half bright and Blue full on. (Additional color controls may be added in a future version.) |
| fontheight | any positive number | fontheight=0.125 | If you use meters as your unit of measure, text will be 12.5 centimeters high. |
| fontjust | LEFT, CENTER or RIGHT | fontjust=CENTER | Each text object will be centered on its specified coordinates. |
| fontname | Some font recognized by your computer | fontname=Times-Roman | It is probably best not to fiddle with font names if your drawing might someday be viewed on someone else's computer, since you won't know what fonts they have available. |
| fontpixels | any positive integer | fontpixels=8 | Text would be 8 pixels high on the screen for VRML 1 images. Not currently supported for VRML 2 output. |
| fontstyle | PLAIN, BOLD, ITALIC or BOLDITALIC | fontstyle=BOLD | Not currently supported for VRML 1 output. |
| linewidth | any positive integer | linewidth=2 | Lines will be drawn 2 pixels wide for VRML 1 images. (Line width is not supported by the VRML 2 language specifications.) |
| speed | any positive number | speed=13.5 |
Helps determine how fast the user moves through your world.
(VRML 2 only.)
Some VRML viewers let the user adjust their speed,
but at least you can establish a default.
Only the last speed value
read by drawwrl.pl will take effect.
speed=1 is "normal" (whatever that might be)
larger numbers are faster, smaller are slower.
If you use
drawbbox.pl
to create a bounding box around your data,
it will also try to compute an appropriate
speed
for you.
If you don't like the value it picks,
you can
|
| transparency | 0.0 to 1.0 | transparency=0.5 | When transparency=0, objects are solid, when 1, they are invisible. Transparency is not fully supported; it may work on some objects and not on others, and your results may vary depending on what VRML viewer you use and your hardware capabilities. |
| viewjump | TRUE or FALSE | viewjump=TRUE |
This is used with viewpoint objects. If while viewing a 3D world you want to move to another viewpoint, viewjump=TRUE will teleport you instantly to the new location, while viewjump=FALSE (the default) will gradually fly you from here to there. Normally the smooth flight effect is more pleasant, so leave the setting at viewjump=FALSE. However if you have a big complicated world that takes a long time to render, you might not want to wait for that animation to play itself out. Set viewjump=TRUE to get there faster. |
Notice that half of the above keywords have to do with text, yet you still probably won't be satisfied. Get over it. VRML is not a text document presentation and formatting language. Don't try to make it one.
The following objects can be created in HoloDraw:
| Keyword | Minimum number of points | Maximum number of points | Example | Notes |
|---|---|---|---|---|
| box | 2 | 2 | box:0 0 0,2 4 6 | The first "point" is actually the location of the box, while the second "point" sets the box's size. Not currently supported for VRML 1 output. Not supported by drawchop.pl which means among other things you can't bend a box into a sphere. |
| line | 2 | no limit | line:0 0 0,0 1 0,1 1 0 | Draws an "L" shaped line. |
| point | 1 | no limit | point:3.1 7.2 23.4 | Plots a point at the specified 3D coordinates. |
| polygon | 3 | no limit | polygon:0 0 0,0 3 0,3 0 0 | Draws a triangle using the current color and transparency (if supported). You can have polygons with more than 3 points, but if you do, it is your responsibility to make sure all the points are in the same plane. |
| sphere | 1 | 1 | sphere:8 2 4,3 | Draws a sphere centered at 8 2 4 with radius of 3 units. Not currently supported for VRML 1 output. |
| text2 | 1 | 1 | text2:1 2 3,Hi, Mom! | Puts the caption "Hi, Mom!" at coordinates 1 2 3 using the current font attributes and 2D letters that always face the user. 2D text does not participate in lighting calculations, so it is faster and always visible (assuming you gave it a reasonable color). Use 2D text for almost every situation where you actually want usable text. Use 3D text (below) to stun your friends with your dazzling new technical abilities. |
| text3 | 1 | 1 | text3:1 2 3,Hi, Mom! | Puts the caption "Hi, Mom!" at coordinates 1 2 3 using the current font attributes and 3D letters that rotate with your world. Not currently supported for VRML 1 output. Probably won't do what you want. 3D text is subject to lighting calculations which are slow and can make the words disappear when viewed from the wrong angle. |
| viewpoint | 1 | 2 | viewpoint: 0 0 -20, 0 1 0, 3.14159265358979, BackSide |
Puts a viewpoint (AKA camera) at coordinates 0 0 -20. You can have as many viewpoints as you want. drawbbox.pl will make a few for you, but you can add more or even eliminate the ones it makes (using "grep -v viewpoint") if you don't want them. When your image loads in a VRML browser, you will usually start out viewing your scene from the first viewpoint that exists in your .wrl file. The second part, 0 1 0, 3.14159265358979 in this example, is optional but you'll probably need it. The first point tells where the camera should be, and this part tells which way the camera should be looking. This is specified using an axis (the 0 1 0) and rotation (3.14159265358979). Imagine that the axis is a line drawn from 0 0 0 to whatever point you specify in your axis parameter. In this case an axis value of 0 1 0 represents an axis line going straight up in the "Y" direction. The rotation parameter tells how far the camera should be rotated around that axis. The value is expressed in radians. 3.14159265358979 radians is 180 degrees. So this viewpoint instruction says "Move the camera -20 units in the Z direction, but then turn it 180 degrees about the Y axis so that it is looking back toward the origin." The final parameter, which is also optional, allows you to name your viewpoint. If you don't provide a name (or if you use the same name twice) HoloDraw will generate a unique name by appending numbers as necessary. Viewpoints are not currently supported for VRML 1 output. |
You can have comments anywhere in a draw file using the "#" character. Anything after a "#" is ignored until the beginning of the next line, but it is preserved and passed along to the next program. You could use this to "tag" certain objects with a comment that would survive processing:
| polygon:0 0 0,0 3 0,3 3 0,3 0 0 # floor |
Then later, after processing with maybe drawsize.pl or drawball.pl, you could grep out "# floor" and feed it to drawbbox.pl.
The HoloDraw format also allows blank lines which may help make your files more readable.
See the examples page for samples of whole draw files, scripts to create and process them, and the resulting output.
Currently the parser tolerates points in the form of X,Y,Z,X,Y,Z
but it really should be X Y Z,X Y Z.
This may become more strict in a future version,
so don't get in the habit of using the X,Y,Z format.
If you have a file of HoloDraw instructions with extra commas,
you can easily remove them using a command
something like this:
drawmove.pl 0 0 0 < drawfile.old > drawfile.fixed
|
|
|