Organica 1.0 File Format V0.8

Djinn/Ritual

This is a description of the OGC format, the one used by Organica 1.0 for Windows. Organica is an easy-to-use modeller that is based on "magnetic" interaction between objects. Actually, all models are 3d blobs. This makes easy modelling of a lot of objects which need a lot of time and/or experience to be done in other common 3d modellers. Among them there are a lot of organic models, hence the name of the program.

Personally, as a demo coder and not as a 3d graphician, I can't see how easiness in modelling animals could help my work. Actually, there's another reason I spent my time on this format. Some time ago I lost a lot of time in reading and understanding 3dstudio's format. It has a lot of totally unuseful info and it is a bit complicated. In the end I did succeed, but converter and loader are all but stable. Instead, OGC format is simple, linear, easy to read, convert and use. Moreover, it's quite useful if you just need to place things in space without worrying about how many faces or vertices they have (talk about blobs, 3d sprites, particles, pizzas in space). Organica also has a keyframer, but I really had too little time to study this functionality and how it saved keyframe data.

For those (few) of you that don't know that words, dwords and floats in memory and in files are "inverted", you'll find in this text two types of "representation": as an hex number (C-style, often followed by size) or as file transcription (enclosed in inverted commas). So a dword could be 0x8 or "08 00 00 00".

In structures all offsets are hex numbers. Floats are intended to be standard Intel 32-bit floats.

Now let's start.

Base structure

    - Header (24 bytes)
    - objects
    - end ("00 00 ff ff ff ff")

 Header:
    00  : File ID (dword: 0x6)
    04  : Base Color - 3 bytes - 0-255 RGB
    08  : "Use object color" enabled - byte - 0=yes 1=no
    0c  : Cube size - float
    10  : Precision - byte - 0 to 10
    14  : Face reduction - float - 0 to 1

Objects

They start, if present, at 0x18, and are identified by Id number and name.

  Block 1:
    00  : 0xffff
    02  : Id - word - see "Object Types"
    04  : Name length (word)
    06  : Name - length as defined above

  Block 2:
    offset from block 1 end:
    00  : 0x8 (dword)
    04  : Position XYZ - 3 floats
    10  : Alignment - 9 floats - rotation matrix around the centre based
          on rotation parameters around axes XYZ given in "Obj. properties"
    34  : Size - float
    38  : Stretch - 3 floats between 1/3 and 3 - default 1 - negative if
          mirrored
    44  : Shear - 3 floats between -0.98 and 0.98 - Max numbers are locked
    50  : More deformations - 3 times this structure:
            3 floats between -1 and 1 with bounds
            3 bytes to express axes to use for deformations:
                taper and twist: 0 to 2 XYZ axes disabled, 4 to 6 enabled
                bend: 0 to 5 axes couples disabled, 8 to 0xd enabled
            First byte and first float refers to bend, second one to taper,
            the third to twist
    7d  : Object disabled - byte - 0=no 1=yes
    7e  : Empty Dword (0x0)
    82  : Mesh Strenght - float - 0 to 10 - default 1
    86  : Color Strenght - float - 0 to 10 - default 1
    8a  : Object Color - 3 bytes - 0 to 255 RGB
    8d  : Empty Byte
    8e  : Group name length - byte - 0 to 63
    8f  : Group name - length as defined above (even non-existant)

  Block 3:
    Shape modifiers levels - a float for each shape mod. (read after notes)

  Block 4:
    A zero (word) (optional: read notes about animations)
    Object ending block - it changes according to family settings:
    - A zero (word) and ending block ("00 00 ff" etc.): end of file
    - A zero (word) followed by 0xffff: a new object begins - it is of
      a different type and it has the same hierarchical level - read from
      block 1
    - A zero (word) followed by "?? 80": a new object begins - it is of
      a type already found and it has the same hierarchical level - read from
      block 2 - ?? is a hex number that identifies the type of the object:
      it's an odd number and starts from 1 (read notes)
    - 0xffff: a new object begins - it's of a new type and is a child of the
      current object - read form block 1
    - "?? 80": a new object begins - it's of ?? type and is a child of the
      current object - read form block 2

If after the first zero there's some other zero (word), it means you are going back one level in the hierarchical tree. The ending block is always placed after you arrive back at the first level. (read examples) If we want to be "exact", the first ending block's word, "00 00", could be the return to the "zero level" of the tree, the one of which the first object is a child.

NOTES:

When a new type is found, a type id is assigned to it and is used in the "?? 80" phrase when a new object of the same type has to be defined. If in a file there are two spheres, the first will have the block 1, the second, no matter where it will be defined, will have just the "?? 80" phrase. Look at examples.

Shape modifiers' number and type change according to object type: they seem to be all float numbers from 0.015 to 1.555 (in hex 0x3fc70d23).

A fast look at animation saving reveals that, if present, keyframe data is located at the end of the file between "00 00" and "ff ff ff ff" of the ending block. Moreover, the objects' definition slightly changes:

- Usual object definition until block 3

- Block 4 is substituted with "?? 80". Object description at keyframe 1 begins (from block 2)

- Last step repeats for each keyframe

- After last keyframe, there's the usual block 4

I have no other info on animations. I have not studied the keyframe data put at the end of file.

Object types (object, name length, name, defined shape modifiers): (in Organica editor order)

    0x3   : Sphere - 0xb - CBlobSphere - Softer
    0x2   : Rod - 0x8 - CBlobRod - Rounder
            Disk - 0x9 - CBlobDisk - Rounder
            Torus - 0xa - CBlobTorus - Rounder
            Cone - 0x9 - CBlobCone - Rounder, Wider
            Cylinder - 0xd - CBlobCylinder - Rounder, Wider
            Rectangle - 0x9 - CBlobRect - Rounder, Longer
            Box - 0x8 - CBlobBox - Rounder, Taller, Longer
            Pyramid - 0xc - CBlobPyramid - Rounder, Taller, Longer
            Wedge - 0xa - CBlobWedge - Rounder, Taller, Longer
            Pie slice - 0xd - CBlobPieSlice - Rounder, Taller, Angle
            Cone slice - 0xe - CBlobConeSlice - Rounder, Taller, Angle
            Bowl - 0x9 - CBlobBowl - Rounder, Deeper
            Concave lens - 0xc - CBlobConcave - Rounder, Deeper,
              !!exceding float 0!!
            Convex lens - 0xb - CBlobConvex - Rounder, Taller
            Bent Rod - 0xc - CBlobBentRod - Rounder, Angle
            Bent Cylinder - 0xc - CBlobBentCyl - Rounder, Thicker, Angle
            Bent Bar - 0xc - CBlobBentBar - Rounder, Taller, Thicker, Angle
            Sphere slice - 0x10 - CBlobSphereSlice - Rounder, Angle
            Barrel - 0xb - CBlobBarrel - Rounder, Taller, Bulge
            Top - 0x8 - CBlobTop - Rounder, Taller
            Hourglass - 0xe - CBlobHourglass - Rounder, Deeper
            Football - 0xd - CBlobFootball - Rounder, Bulge
            Tube - 0x9 - CBlobTube - Rounder, Longer
            Disk slice - 0xe - CBlobDiskSlice - Rounder, Angle

Examples:

- A bent bar:

        Header
        0xffff 0x0002 0x000c "CBlobBentBar" 0x00000008 etc.etc. ;bar
        0x3fc70d23 0x3fc70d23 0x3fc70d23 0x3fc70d23   ;4 shape mod
        0x0000                 ;bar def. end
        0x0000                 ;no child
        "00 00 ff ff ff ff"    ;end of file

- Two barrels not grouped:

        Header
        0xffff 0x0002 0x000b "CBlobBarrel" 0x00000008 etc.etc.  ;first barrel
        0x3fc70d23 0x3fc70d23 0x3fc70d23                        ;3 shape mod
        0x0000                 ;first barrel ends
        0x0000                 ;first barrel has no child
        0x0180 0x00000008 etc. etc.                             ;second barrel
        0x3fc70d23 0x3fc70d23 0x3fc70d23                        ;3 shape mod
        0x0000                 ;second barrel ends
        0x0000                 ;second barrel has no child
        "00 00 ff ff ff ff"    ;end

- Two grouped barrels:

        Header
        0xffff 0x0002 0x000b "CBlobBarrel" 0x00000008 etc.etc.  ;first barrel
        0x3fc70d23 0x3fc70d23 0x3fc70d23                        ;3 shape mod
        0x0000                 ;first barrel ends
        0x0180 0x00000008 etc. etc.                             ;second barrel
        0x3fc70d23 0x3fc70d23 0x3fc70d23                        ;3 shape mod
        0x0000                 ;second barrel ends
        0x0000                 ;second barrel has no child
        0x0000                 ;first barrel's family ends here
        "00 00 ff ff ff ff"    ;end

        Hierarchy:
        I  level:            barrel1
                                |
        II level:            barrel2

- Two spheres, one is the other's child; two tubes, children at the same level to the first sphere; a third independent sphere: (if you understand this, I have nothing more to teach about groups!)

    Header
    0xffff 0x0003 0x000b "CBlobSphere" 0x00000008 etc. etc. ;first sphere
    (Shape mod=) 0x3fc70d23 0x0000                          ;first sphere ends
    0x0180 0x00000008 etc.etc.                              ;second sphere
    (Shape mod=) 0x3fc70d23 0x0000                          ;second sphere ends
    0x0000                 ;second sphere has no child
    0xffff 0x0002 0x0009 "CBlobTube" 0x00000008 etc.        ;first tube
    (Shape mod=) 0x3fc70d23 0x3fc70d23 0x0000               ;first tube ends
    0x0000                 ;first tube has no child
    0x0380 0x00000008 etc.                                  ;second tube
    (Shape mod=) 0x3fc70d23 0x3fc70d23 0x0000               ;second tube ends
    0x0000                 ;second tube has no child
    0x0000                 ;first sphere has no other child
    0x0180 0x00000008 etc.etc.                              ;third sphere
    (Shape mod=) 0x3fc70d23 0x0000                          ;third sphere ends
    0x0000                 ;third sphere has no child
    "00 00 ff ff ff ff"    ;end

        Hierarchy:
        I  level:              sph1             sph3
                            /   |   \
        II level:        sph2  tub1  tub2

- A bent bar - animation is present, one keyframe; compare with first example:

    Header
    0xffff 0x0002 0x000c "CBlobBentBar" 0x00000008 etc.etc. ;bar
    0x3fc70d23 0x3fc70d23 0x3fc70d23 0x3fc70d23         ;4 shape mod
    0x0180 0x00000008 etc.etc.                  ;first keyframe's description
    0x3fc70d23 0x3fc70d23 0x3fc70d23 0x3fc70d23         ;4 shape mod
    0x0000                 ;bar ends
    0x0000                 ;no child
    "00 00 01 00" etc. etc.    ;keyframe data starts
    "ff ff ff ff"              ;end

I'd like to greet all my friends in the scene and to thank a lot of them who helped me to grow up in it.

If anyone succeeded in understanding keyframe data or found this document useful or just likes it, please contact me: djinn@tiscalinet.it

Organica is copyrighted by Impulse Inc.
I'm in no way connected to Impulse Inc. or to Organica Team.
I can't be considered responsible for any harm to people or things due to reading this document.

- Djinn/Ritual