As we explain in other pages of this site, the VR Cocha club uses a specific ASCII text format as a unique source to produce 3D files in various standard formats. As our club was founded in Cochabamba, Bolivia, the name of our format is Cochabamba (and the extension is .CBB).

Before we begin, we must say something about :

Files written in the CBB format are plain DOS ASCII text files, with ends of lines coded as chr$(13) and chr$(10). There is normally a chr$(26) character at the end, although its absence should have no consequence. In other words, these files are exactly what the DOS EDIT program normally writes. Macintosh ASCII files and Unix ASCII files code the end of lines in a slightly different way, and that may cause some minor incompatibility problems; but DOS and Windows users can forget that.

The CBB format uses a line-by-line logic. That means that (unlike what is done with HTML or VRML) you cannot put end of lines anywhere in the files, but only when a complete piece of information has been defined. In a symetric way, you cannot put two independent pieces of information on the same line. In other words, to define a point, a face, a color or a basic shape, you'll always have to use exactly one line.

Every line constitutes a piece of information, but various lines are grouped in logical units by markups. The markups to open a logical unit have the form <markup> (inferior sign, name of the markup, superior sign; all that constitutes one independent line), and the markups to close a logical unit have the form </markup> (inferior sign, slash, name of the markup, superior sign; all that constitutes another independent line). This is obviously inspired from HTML, but do not forget that the CBB format uses a line-by-line logic and not an opening sign-closing sign logic as HTML and VRML do.

The CBB format uses a cartesian 3-dimensional coordinate system. The X axis is horizontal and its direction is eastwards. The Y axis is horizontal and its direction is northwards. The Z axis is vertical and its direction is upwards.

The unit for lengths and distances is meters. The unit for angles is degrees.

As the VR Cocha club was founded in Bolivia, the very few keywords we use at the present time are... Spanish words. It would not have been absurd to translate them in the material we publish on this Web site, but it would have created compatibility problems with the material we already created here, in Bolivia. So we thought it would be more reasonable to go on with a little bit of Spanish vocabulary. This should not be a big problem, as the geometry words are more or less international: cubos means cubes, cilindros means cylinders, etc.

Anyway, this is a complete list of our keywords:

- Simple shapes

n, s, e, o, ne, no, se, so, inf, sup, (norte, sur, este, oeste, nordeste, nordoeste, sudeste, sudoeste, inferior, superior or, in English, north, south, east, west (take care: west is written o and not w), northeast, northwest, southeast, southwest, inferior, superior) to define positions or exclusions.

- Complex shapes

<lados> and </lados> (sides) are the markups to define faces.

- Miscellaneous

Simple shapes are cubes, cylinders, cones and spheres, but their x, y and z proportions can be modified to create parallelepipeds and oval shapes.

Simple shapes are always defined in a parallelepiped whose sides are parallel with the axes x, y and z (of course, it is possible to move and rotate them afterwards). You will define the position and proportions of this parallelepiped, which are not always the same as the ones of the included shape. Have a look at these examples:

- Syntax
The syntax for a line defining a simple shape is this one:
Posi Xcoord,Ycoord,Zcoord,ReferencePoint Tama Xsize,Ysize,Zsize

If the shape is a cone or a cylinder, it is recommended to add on the same line:
Punt NumberOfPointsInTheCircle

And if the shape is a sphere, it is recommended to add:
Punt NumberOfMeridians,NumberOfParallels

- Position and reference point
The position of a simple shape is given in reference with the bottom side of the parallelepiped in which it is contained. Nine points of this rectangle can be used: its center (c), its four angles (no, ne, so, se) and the four centers of the lines of its perimeter (n,s,e,o).

In this series of examples, the green spot indicates where is the point used as a reference.

This feature is extremely useful in architecture: it is much easier to determine where are the corners of a wall than its center.

In order to reduce the number of triangles that your browser will have to deal with, the CBB format use two techniques: it may destroy the sides of a shape that are not supposed to be seen, and reduce the number of vertices in a round shape.

- Destroying unnecessary sides
You can reach that result adding on the line that defines the shape the abbreviation Excl followed by the names of the sides you want to destroy. For instance, these are some examples of what you can do with a parallelepiped:

Have a look at the "Mormon temple" in the Examples section. It is a typical example of what you can do with that feature of the CBB format, not only with parallelepipeds, but also with round shapes.

- Reducing the number of vertices in a round shape
As all the shapes have to be divided in triangles to be represented by virtual reality programs, round shapes represent much more work for them than square shapes. A complete cube has six faces, which already means twelve triangles. A sphere represents much, much more: even with more than one hundred triangles, a sphere does not seem really round if you are near from it. But you are not always near from it: sometimes you will not need an extreme accuracy if you just want to draw a small spot. Well, the CBB format allows you to define exactly how accurate any of your round shapes will be. Have a look at these examples:

We have already described in another page of this site the general method to define a shape by its characteristic points. The syntax we use in the CBB format is extremely simple and does not need many explanations.

- Syntax
The lines that define a vertex are written between the markups <puntos> and </puntos> (puntos means points). They must have that structure:
PointNumber,Xcoord,Ycoord,Zcoord

The lines that define a face are written between the markups <lados> and </lados> (lados means sides). They must have that structure:
FirstPoint,SecondPoint, (...) LastPoint

- Non-triangular sides
Sides defined with more than three vertices will be cut in triangles, each of these using the first point as an angle. Be careful where the first point is if all the angles of the perimeter do not look towards its center. If necessary, cut the perimeter into pieces.

As the computer screens form the colors melting red, green and blue spots, nearly all the Virtual Reality programs force their users to define colors according to that abstract and complicated model. In the VR Cocha Club, we think that computation should adapt itself to human logic, not the countrary. For that reason, we prefer to define colors with a hue-saturation-grayscale model, which is much easier to understand.

- Syntax
The single line that defines a color must be written between the markups <color> and </color>. It must have that structure:
Hue,Saturation,Grayscale

Hue is a position on the classic chromatic circle. That value will be expressed in degrees, as you can see on this figure:

Saturation is a value between 0 and 1. The bigger the value, the more aggressive the color will be. If saturation is set to 1, the color will be pure; if it is set to 0, it will only be gray.

Grayscale is also a value between 0 and 1. The bigger the value, the brighter the color will be. If grayscale is set to 1, the color will be white; if it is set to 0, it will be black.

It would be boring and absurd to have to calculate the coordinates of an object everytime you want to modify its place or orientation only, without changing its aspect at all. The CBB format allows you to move, rotate or modify the proportions of any object adding only a few lines in the source file. You can also write long series of modifications of coordinates of that type, and combine them in logical structures.

- Let's begin with an example
As we do not want to be too abstract, please have a look immediately at the following series of examples. In fact, it is five variants of the same example (let's say the idea is to represent a pistol bullet put on the floor), but its complexity is increased gradually.

On the right side, you can see the CBB code that produces each scene. Do not try to understand the whole syntax at the present time, just notice when moving, scaling and rotating are used, and where are the lines that we added to do that (the new lines appear in green, and the most important in bold characters). You'll come back to these examples after having read the explanations that follow. You'll understand that it is much simpler than it seems at the beginning.

Moving near the O point,
then scaling

Moving near the O point,
then scaling,
then rotating

Moving near the O point,
then scaling,
then rotating,
then moving far from the O point

And now, let's see all that in detail.

- Markups
Each of the two groups of lines must begin with the markup <modifcoord> placed on an independent line, and finish with the markup </modifcoord> placed on another independent line. You will write the instructions to define the modification of coordinates or to put an end to it between these two lines.

- Syntax
The line to define a move must have this form:
Posi Xmove,Ymove,Zmove

The line to define a scaling must have this form:
Tama Xscale,Yscale,Zscale
If you want the scaling to be homogeneous, write thrice the same value. If you want some coordinates to remain unchanged, write 1 as scale factor. Negative factors may be used (and are useful for symetry). Never use 0 as a scale factor.
The line to define a rotation around the X axis must have this form:
Rotx AngleInDegrees

The line to define a rotation around the Y axis must have this form:
Roty AngleInDegrees

The line to define a rotation around the Z axis must have this form:
Rotz AngleInDegrees

Rotations around the Z axis are the most common, as they are the ones that allow you to modify the orientation of an horizontal object. Rotations around the X and Y axes are generally orthogonal, and used to transform an horizontal object into a vertical one or viceversa.

- General logic
A correct modification of coordinates will be written with two groups of lines: a first one to define the modification, a second one to put an end to it. The lines that define the shape whose coordinates you want to modify will be written between these two groups of lines.

- Defining the modification of coordinates
You must use one independent line for each modification of coordinates, but you can write series of modifications between the opening and closing markups. These modifications will be executed one after the other, so the order with which you write them is important.

In order to understand the result, we recommend that you use the order we have seen in the example:

This feature allows you to call a CBB file from another. Generally, this will be used so that a file describing a complex scene will call some simpler objects: a file describing a house will call files describing rooms, a file describing a room will call files describing its furniture, a file describing a chair will call files describing its legs, etc.

The current version of our translating program manages one hundred hierarchical levels... and you'll probably never need more than ten.

The coordinates of the included files may be modified with the modifcoord instructions we just saw: you'll only have to write the lines describing the inclusion between the two modifcoord groups of lines. This is extremely useful, especially if you work with other fans' files and do not want to lose time to understand their logic: you just include them where you want.

The same file may be called various times by a file of higher hierarchical level. For instance, you can use four times the same file describing a chair to put four different chairs around a table. That makes your code smaller, easier to understand, to test and to modify.

- Syntax
To call a file from another, you will use three lines of this type:
<inclusion>
DOSNameOfTheFile
</inclusion>

The DOS name of the file may not include its path, if you launch your Basic interpreter from the correct subdirectory when you translate the file.

Nothing new: we already talked about that topic in the other pages of this site. We only wanted to insist on the fact that all the efforts you will do to understand our format will be useful to you when you work with more standard software, as you can translate all the CBB files that you'll write with our translating program.

Enjoy, and let us know your creations... or the problems that you've met.