HoloDraw Program Documentation: drawbbox

Program Summary

Discussion

This makes a box around an object.
Believe it or not, this is one of the most complicated things
about making a nice 3D image. So be prepared for lots of options...

Except for attributes (e.g. color) you might have set,
this program does NOT echo the input to output; this gives you the option
of creating a box around an object without actually showing that
object. In other words, you can make generic boxes or gridlines
just by specifying the two opposite corner points.
For example, these commands in a shell script...

  echo 'point:268 1 -2900,272 14 -2500' |
    drawbbox.pl -B1+1/3+1/200+1SWI > box.draw

... would make a cube from 268,1,-2900 to 272,14,-2500 with tickmarks.
This same technique is useful to make a box that begins and ends on
even increments when your object is not so nicely aligned, for example
the object's X axis goes from 0.3 to 12.85 but you want a box from
0 to 13.

In the normal case when you DO want to see your object too,
you must separately include it in the files input to drawiv.pl or drawwrl.pl
as in "cat pic.draw box.draw | drawwrl.pl > pic.wrl"

This program sets default attributes such as the line width to be used when
drawing the box.
You will probably want to override that by inserting those instructions in the
input to this program. For example:
color = 1 0 0    # make my data red
point:1 2 3      # and so on with the rest of your data...
color = 0 1 0    # make my bounding box green
fontheight = 33  # control the size of the annotations

When you pipe the above 4 lines to drawbbox.pl, the second color attribute
will override the first, and the fontheight attribute will override the
drawbbox.pl default. So your bounding box will be green and your annotations
will be size 33.

Note also that you can run drawbbox.pl several times to create several boxes
and combine them all in your final image. So you could put a large blue box
around your whole data set and a small red box around an area of special
interest. Similar tricks can create frequent tickmarks with less frequent
annotations, tickmarks that go out AND grid lines that go in, etc.

So if you want multiple colors or line widths for, say, various sides
of the box or for tick marks vs. box lines, try running drawbbox.pl
several times, once for each attribute combination, with only those
features you want in that color turned on.

TICK MARKS

This can also (and will by default) make tickmarks and annotate them
with your X Y and Z dimensions.

Performance note: In some VR browsers, text can significantly impact
rendering speed.
If your model is too slow, minimize the number of annotated tickmarks
or omit the bounding box entirely.

You can control how often the tickmarks occur and how big they are.
If you don't set anything it tries to make a decent guess,
but your mileage may vary. If you care, set them explicitly.

For those familiar with GMT, the "tickinfo" argument uses a LIMITED
implementation of the same syntax, with some ENHANCEMENTS to specify
tick length. This means your tickinfo strings from GMT scripts MAY
have a similar effect here.

However, the normal GMT plot (like many graphs) is 2D so there are
only 4 bounding lines to consider, and text is all flat with respect
to the paper or screen. A 3D cube however has 12 bounding lines,
and tick marks and text could extend in the Z dimension as well.
This makes for many more permutations of tick placement info.

LINE NAMES

GMT names the 4 lines around a plot W S E and N for the compass
directions, and on the occasional 3D plot one of the vertical lines
is called Z. This program keeps those defined "line names" and names
the remaining lines according to a similar if mostly meaningless
pattern:

        THIS FACE IS CLOSEST TO YOU
        +-------------------------+
       /|||||||||||  M  |||||||||.|
      / ||||||||||||   |||||||  .||
    I/  ||||||||||||||||||||| H. ||
    /   ||||||||||||||||||||| . |||
   /    ||||||   ||||||||||||.|||||
  + . . ||.|. . . .|.|.|.|.|+|||| |
  |     |||||  N  ||||||||||.|||  |
  |    V||||||   |||||||||||.||| D|
  |     ||||||||||||||||||||.|||  |
  |     ||||||||||||||||||||.|||| |
  |     ||||||||||||||||||||.||||||
  |     ||||||||||||||||||| .||||||
  |     ||||||||||||||||||  .||||||
 W|     |||||||||||||||||| E.||||||
  |     ||||||||||||||||||  .||||||
  |     +-------------------------+
  |    ////////////  R  ////./////
  |   //////////////  //////./  /
  | Z///////////////////////. J/
  | ////////////////////////. /
  |/////////////////////////./
  +-------------------------+
               S

GMT vs. drawbbox.pl

In GMT, you mention a line name if you want that axis drawn.
If you use upper case you get annotation on that line,
but if you use lower case you get the axis with ticks only.
There does not seem to be a way to get an axis with no ticks.

In this program, it initially starts with every line defaulted on.
But if you name some lines, the others get shut off.
Like GMT, every line gets tickmarks.
Unlike GMT, you can make some tickmarks go away by setting their
length to zero.

Usually you don't want tick marks on every axis; the bounding box
ends up looking like a porcupine.

By default V S and H get tick marks and annotations, and all 12 box lines
are drawn. It might seem more expected to default to lines S W and Z
but they intersect causing problems with annotations colliding.
Lines V S and H never touch, so they are the default instead.

The basic options are
TickFreq - how often (in whatever units you use) do you want a tick?
TickLen  - how long (in whatever units you use) should the ticks be?
Generally these will be the same for X, Y and Z
but you can set the overall default and then override for Y and Z.

Tickmarks can be suppressed entirely by setting TickLen(X/Y/Z) to zero
(using the notation -0 or +0, see t+l and t-l below)
or you can turn them on for individual lines by line name (see diagram).


Currently supported options are:

-Bt
Sets TickFreq to the same t in X, Y and Z.
(In all cases Y and Z settings are copied from X by default.)

-Bt/t/t
Sets individual TickFreq for X, Y, and Z.
If you only specify X/Y then Z will be the same as X.
To accept the default for X and y, but specify Z,
leave the X and Y spots null, as in //t.

Similar X/Y/Z repetition can be used with the options below.

-Bt+l
Sets TickFreq to the same t in X, Y and Z
and TickLen to the same l in X, Y and Z.
Ticks go OUTSIDE the bounding box.
This is the recommended and default tick direction.
When annotation is enabled, text appears at the end of the tick line.

-Bt-l
Sets TickFreq to the same t in X, Y and Z
and TickLen to the same l in X, Y and Z.
Ticks go INSIDE the bounding box.
This may not be a good idea. Tick lines may intersect each other
and/or be invisible at corners. They may interfere with what you are
trying to see. On the other hand, if you want to draw a grid all
the way across your image, use long negative tick lines.
For example, if your image is 100 units across, use -100 for TickLen

Note further that you can have BOTH such a grid AND external tickmarks
simply by running drawbbox.pl twice: once to plot the grid and again to
plot the external tickmarks.

-B[anything above][line names]
Turns lines and tickmarks on for named axes; see names diagram above.
By default you get VSH but if you specify any axes the default ones
go away.

By the way, try plusdraw.pl if you want occasional markers WITHIN your
space, like this:
.---------------------------------------------------------------------.
|                                                                     |
|         +         +         +         +         +         +         |
|                                                                     |
.---------------------------------------------------------------------.


EXAMPLE

-B1+2/3+4/5-6DEMNRSVW
Sets TickFreq to 1 for X, TickLen +2 means tick lines will go outward.
Sets TickFreq to 3 for Y, TickLen +4 means tick lines will go outward.
Sets TickFreq to 5 for Z, TickLen -6 means tick lines will go inward.
Tick marks will be drawn on lines N E S W (North, East, South and West)
and on the corresponding lines M D R and V. No lines in the Z direction.

Written by Marvin Simkin Filename drawbbox.html Last updated April 5, 2005