The Cochabamba format

This page was last modified on the 18th of August, 1997.


The information published in this page will be much easier to understand if you run the listings we publish in the Examples part and look at the ASCII files produced with a word processor.

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 :

  • General aspects of our format
  • Its keywords

    That having been said, the features allowed by our format are these :

  • You can create simple shapes very easily
  • You can create truncated and simplificated shapes
  • You can define any shape by its characteristic points
  • You can define colors with a simple hue-saturation-grayscale model
  • You can modify the coordinates of any shape (moving, scaling and rotating them)
  • You can use hierarchical structures
  • And, last but not least, you can transform all that to standard files.


  • Logo

    General aspects of the format

    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 only uses 7-bit ASCII characters: no characters with accents are ever used. That means you can forget the difference between DOS ASCII texts and Windows ASCII (ISO) texts.

    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 lines must begin and end with a readable character. They cannot begin or end with a tab or a space character.

    The VR Cocha format is not case-sensitive.

    There cannot be empty lines between an opening and a closing markup. Empty lines between a closing and an opening markup will be ignored.

    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.


    Logo

    The keywords

    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:

    Puls - Simple shapes

  • <cubos> and </cubos> (cubes) are the markups to define parallelepipeds;
  • <cilindros> and </cilindros> are the markups to define cylinders;
  • <conos> and </conos> are the markups to define cones;
  • <esferas> and </esferas> are the markups to define spheres.
    The lines between these markups use the abbreviations:
  • Posi (posición, position) to say where the shape is;
  • Tama (tamaño, size) to define the dimensions of the shape;
  • Punt (puntos, points) to define the number of vertices in a round perimeter;
  • Excl (exclusión, exclusion) to get rid of certain faces of a shape;
  • 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.

    Puls - Complex shapes
  • <puntos> and </puntos> (points) are the markups to define vertices;
  • <lados> and </lados> (sides) are the markups to define faces.

    Puls - Miscellaneous
  • <color> and </color> are the markups used to define colors (England-English speakers, please notice we write color with o and not with ou);
  • <nombre> and </nombre> (name) are the markups used to give names to the shapes in the VRML or Caligari exported files; if these markups are not used, the exported files will include the word Objeto, which means Object.
  • <inclusion> and </inclusion> are the markups used to include a CBB file in another (Spanish-speaking readers, please notice that we write inclusion without accent, for reasons of compatibility with the 7-bit ASCII character set);
  • <modifcoord> and </modifcoord> are the markups to modify the coordinates of any shape.
    The lines between these last two markups use the abbreviations:
  • Posi (posición, position) to move objects without modifying their aspect;
  • Tama (tamaño, size) to modify their size or proportions;
  • Rotx, Roty, Rotz to rotate objects around the axes x, y and z.

  • Logo

    Create simple shapes very easily

    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:

    Cube
    Cylinder
    <cubos>
    Posi 1.5,1,0,so Tama 2,2.5,1.5
    </cubos>

    <cilindros>
    Posi 1.5,1,0,so Tama 2,2.5,1.5 Punt 36
    </cilindros>

    Cone
    Sphere
    <conos>
    Posi 1.5,1,0 Tama 2,2.5,1.5 Punt 36
    </conos>

    <esferas>
    Posi 1.5,1,0 Tama 2,2.5,1.5 Punt 18,18
    </esferas>

    Circular sides of cones and cylinders are horizontal (unless you rotate them). The arrow of a cone is put upwards (unless you rotate it).

    Puls - 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

    Puls - 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).

    Reference vertices

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

    Position se
    Position s
    Position so
    Posi 1,1,0,se Tama 1,1,1

    Posi 1,1,0,s Tama 1,1,1

    Posi 1,1,0,so Tama 1,1,1

    Position e
    Position c
    Position o
    Posi 1,1,0,e Tama 1,1,1

    Posi 1,1,0,c Tama 1,1,1
    or
    Posi 1,1,0 Tama 1,1,1
    Posi 1,1,0,o Tama 1,1,1

    Position ne
    Position n
    Position no
    Posi 1,1,0,ne Tama 1,1,1

    Posi 1,1,0,n Tama 1,1,1

    Posi 1,1,0,no Tama 1,1,1

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


    Logo

    Create truncated and simplificated shapes

    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.

    Puls - 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:

    Excl sup
    Excl sup,n,s
    <cubos>
    Posi 1.5,1,0,so Tama 2,2.5,1.5 Excl sup
    </cubos>

    <cubos>
    Posi 1.5,1,0,so Tama 2,2.5,1.5 Excl sup,n,s
    </cubos>

    Excl n,s,o,inf
    Excl inf,sup,s,o
    <cubos>
    Posi 1.5,1,0,so Tama 2,2.5,1.5 Excl n,s,o,inf
    </cubos>

    <cubos>
    Posi 1.5,1,0,so Tama 2,2.5,1.5 Excl inf,sup,s,o
    </cubos>

    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.

    Puls - 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:

    Puntos 4,3
    Puntos 6,5
    Puntos 6,9
    Posi 1,1,0 Tama 1,1,1 Punt 4,3
    8 triangles

    Posi 1,1,0 Tama 1,1,1 Punt 6,5
    36 triangles

    Posi 1,1,0 Tama 1,1,1 Punt 6,9
    84 triangles

    Puntos 12,5
    Puntos 18,17
    Puntos 18,17 Excl
    Posi 1,1,0 Tama 1,1,1 Punt 12,5
    72 triangles

    Posi 1,1,0 Tama 1,1,1 Punt 18,17
    540 triangles

    Punt 18,17 Excl n,inf
    135 triangles


    Logo

    Define any shape by its characteristic points

    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.

    Puls - 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 number of the first point is 1 and not 0. Defining points that will not be used in the description of sides, or leaving gaps between used points, will have no consequence except a useless occupation of memory.

    Although we always do it and think you should do it too, it is not necessary to define the points in a regular order from number 1 to the biggest number.

    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

    We recommend that the list of points should be written counterclockwise (looking from outside the object).

    Puls - 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.

    Cutting a non-triangular perimeter

    Logo

    Define colors with a simple hue-saturation-grayscale model

    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.

    Puls - 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:

    Chromatic circle

    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.

    For instance, here are some variants of the same colors, realized with small changes of the saturation parameter, leaving unchanged the hue and grayscale parameters. From left to right, the values for saturation are 0, 0.2, 0.4, 0.6, 0.8 and 1.

    Examples of saturation

    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 is important to notice that, in our model, the hue value has no influence on the grayscale: blue is not darker than yellow, for instance. Look at what the chromatic circle becomes when saturation is set to 0 (in other words, when everything is converted to gray). Grayscale is set to 0 at the center of the circle, and set to 0.8 on its perimeter.

    Gray circle

    Logo

    Modify the coordinates of any shape

    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.

    Puls - 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.


    Basic shapes

    Basic shapes
    At the beginning, we only have a cylinder and a sphere. Both of them were defined in reference with the southwest angle of the bottom side of the parallelepiped in which they are included, as we explained earlier. At the present time, the sphere is inside the cylinder.

    <cilindros>
    Posi 0,0,0,so Tama 1,1,1 Punt 12
    </cilindros>

    <esferas>
    Posi 0,0,0,so Tama 1,1,1 Punt 12,11
    </esferas>

    Moving near the O point

    Moving near O
    Each of the two objects is now moved so that the O point could be in some strategic place (because scaling and rotating are always done in reference with the O point).
    In order to do that move, we added two groups of lines around the code that describes each of the basic shapes: a first group to define the modification of coordinates, and a second group to put an end to it so that the following code should not be affected.

    <modifcoord>
    Posi -0.5,-0.5,-1
    </modifcoord>

    <cilindros>
    Posi 0,0,0,so Tama 1,1,1 Punt 12
    </cilindros>
    <modifcoord>
    Fin
    </modifcoord>


    <modifcoord>
    Posi -0.5,-0.5,-0.5
    </modifcoord>

    <esferas>
    Posi 0,0,0,so Tama 1,1,1 Punt 12,11
    </esferas>
    <modifcoord>
    Fin
    </modifcoord>

    Moving near the O point,
    then scaling

    Scaling
    Scaling is nothing more than a multiplication of the coordinates. For that reason, it was useful to put the objects in a correct location in reference with the O point, so that we can scale them without moving them. We only had to add a single line for each object to do that scaling. For X and Y coordinates, the multiplication parameter is 1; that means that these coordinates will remain unchanged.

    <modifcoord>
    Posi -0.5,-0.5,-1
    Tama 1,1,2
    </modifcoord>
    <cilindros>
    Posi 0,0,0,so Tama 1,1,1 Punt 12
    </cilindros>
    <modifcoord>
    Fin
    </modifcoord>

    <modifcoord>
    Posi -0.5,-0.5,-0.5
    Tama 1,1,2
    </modifcoord>
    <esferas>
    Posi 0,0,0,so Tama 1,1,1 Punt 12,11
    </esferas>
    <modifcoord>
    Fin
    </modifcoord>

    Moving near the O point,
    then scaling,
    then rotating

    Now, the two basic shapes have exactly the aspect that we wanted, but we do not want their orientation to remain parallel with the three axes. So we will now rotate the objects around these axes.

    Rotating
    First, an orthogonal (90-degree) rotation around the X axis, so that the vertical shape should become horizontal. Second, a free rotation around the Z axis.
    To do all that, it is not necessary to move the two shapes independently, and the added code is global: a group of lines at the beginning, another group of lines at the end, all the rest remaining unchanged.
    Notice that this rest already contains modifications of coordinates. That means that modifications of coordinates can be put in logical structures.

    <modifcoord>
    Rotx -90
    Rotz 30

    </modifcoord>


    <modifcoord>
    Posi -0.5,-0.5,-1
    Tama 1,1,2
    </modifcoord>
    <cilindros>
    Posi 0,0,0,so Tama 1,1,1 Punt 12
    </cilindros>
    <modifcoord>
    Fin
    </modifcoord>

    <modifcoord>
    Posi -0.5,-0.5,-0.5
    Tama 1,1,2
    </modifcoord>
    <esferas>
    Posi 0,0,0,so Tama 1,1,1 Punt 12,11
    </esferas>
    <modifcoord>
    Fin
    </modifcoord>

    <modifcoord>
    Fin
    </modifcoord>

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

    Putting in place
    The proportions of the object are now correct, and so is its orientation: we only have to put the whole thing as it is in the location that we want. To do that, we only need to add one line in the correct place.

    <modifcoord>
    Rotx -90
    Rotz 30
    Posi 2,2,0.5
    </modifcoord>

    <modifcoord>
    Posi -0.5,-0.5,-1
    Tama 1,1,2
    </modifcoord>
    <cilindros>
    Posi 0,0,0,so Tama 1,1,1 Punt 12
    </cilindros>
    <modifcoord>
    Fin
    </modifcoord>

    <modifcoord>
    Posi -0.5,-0.5,-0.5
    Tama 1,1,2
    </modifcoord>
    <esferas>
    Posi 0,0,0,so Tama 1,1,1 Punt 12,11
    </esferas>
    <modifcoord>
    Fin
    </modifcoord>

    <modifcoord>
    Fin
    </modifcoord>


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


    Puls - 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.

    Puls - 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.

    Puls - 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.

    Puls - 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:

  • first, move the object near the O point (the intersection of the X, Y and Z axes), so that this point would be in a good position for rotations and scalings (rotations and scalings will be done using the O point as a reference); a correct position is one that will allow you to understand the result of rotations and scalings; generally, the logic is much easier to follow if you choose the center of the bottom side of the object, or one of its angles;
  • second, scale the object while its own axes are still parallel with the X, Y and Z axes;
  • third, rotate the object; it will be easier to understand if the rotation around the Z axis is the last one;
  • fourth and last, move the object to its correct location in the scene (this location may be very distant from point O);

    Of course, you can skip one or more of these steps if you do not need it.

    Puls - Putting an end to the modification
    You will only have to write the word Fin on a single line between the two markup lines (Fin means End in Spanish). This simple instruction will forbid the previous modification of coordinates to influence the further lines.

    Fin does not put an end to all the modifications of coordinates, but only to the current one. If there is an imbrication of modifcoord instructions, Fin will only have the effect to come back to the previous logical level of modifications.


  • Logo

    Use hierarchical structures

    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.

    Puls - 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.


    Logo

    Transform all that to standard files

    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.


    Back to the VR Cocha home page
    This page hosted by Get your own Free Home Page
    1