CONTENTS

   Overview of Terranim8or v7
    User instructions
    Known issues
    Bug reports
    Download instructions


Overview of Terranim8or v7


Terranim8or is capable of loading / viewing / playing / editing / and saving .an8 files. Though it doesn't contain yet all the planned features, it has some capabilities that could be useful right now:

  • Opening damaged files: Terranim8or's policy is to try opening and rendering broken .an8 files, while issuing a warning, as an attempt to recover objects from invalid files. An error log file is generated containing a description of the error(s) encountered by the parser and its (their) location in the file. Sometimes this information can save a lot of time in debugging a broken .an8 file.
  • Terrain: Arbitrary size (resolution) terrains can be generated from height maps (gray-scale, or color images). Animated terrains (suited for ocean, running water or clouds simulation) are generated by fractal noise algorithm. 
  • Automatic terrain texturing is also available.
  • Displacement maps: Easy mesh modeling with displacement maps (gray-scale, or color images)
  • Mesh polygon reduction: Simplifying high poly count models.
  • Instant cube environment mapping
  • Plug-in capability for implementing effects. For the available plug-ins, see the "Download Instructions" section.
  • Triangulation: Splitting the faces of arbitrary meshes to triangle faces
  • Saving the contents of the workspace (wire frame, or smooth) to usual image formats, including PNG and TIFF
  • Handling multiple components selections: An object can be added to a scene in multiple instances at once. Multiple components selections can be positioned (moved, rotated) and scaled entering numeric values. Object arrays can be created easily (See Edit -> Locate -> Custom...)
  • Copy / Paste operations for object / scene elements, including materials, lights and cameras
  • Boolean operations (plug-in): Boolean subtraction, union and intersection on two closed meshes
  • Controller script in-place evaluation, useful for learning ASL

Implemented features: Parametric objects, meshes, morph targets, subdivision, paths, text components, reference image, groups. Terranim8or computes normals and subdivision in such a way that yields visually identical results with Anim8or (though, it's not the fastest way to computing normals...). Wire, flat, smooth shading. Global antialiasing. Solid color / image / panorama background, fog, ground grid, near - far clip planes. Directional / local / spot lights. Multiple cameras. Scene object elements, targets. Relative orientations: world, facing target, orient target, facing path. Full parent - child hierarchy. Animation controllers for visibility, position, orientation, scale, color, field of view, active camera, morphs. ASL internal scripts supported (a subset of ASL used for controller scripts). Material editor (not yet finished). The objects, camera and ground grid were set, scaled and positioned to result in identical placements in the window with Anim8or (provided that Anim8or and Terranim8or's windows are resized to the same size)

Limitations: A single Anim8or file can be loaded / edited at a time. The available modes are Object Edit and Scene Mode. Figures are ignored when playing an animation. Materials are rendered with many limitations (so does Anim8or in the workspace). Available real time material properties: ambient, diffuse, specular and emissive colors. Global object transparency, roughness. Diffuse texture. Transparency maps, cube environment maps. Blend modes: decal, darken, lighten. ASL is limited to features used for controller scripts, so don't expect object editing routines!
I will try to add more real-time material properties in the future.

Safety notes: An Anim8or file opened, then saved by Terranim8or v7, keeps all the information from the original file unchanged.
Theoretically it is safe to edit an .an8 file in Terranim8or. As there are always possibilities for a crash, the safest way is to open the .an8 file in Terranim8or and "Save As..." it immediately, to keep the original intact.

Windows notes: The application was designed for Windows XP. To keep persistent user interface variables, Terranim8or v7 adds the following registry entry:
HKEY_CURRENT_USER/Software/Leslie's Software/Terranim8or with the following sub keys: Background Color, Recent Files List and Settings.
On systems which have incompatible registry, or do not grant permission for Terranim8or to write to the registry, the impact should be only the absence of the most recently used files list, loss of the customized background color when closing the application and impossibility to launch Anim8or from within Terranim8or.



User instructions

The interface and mouse commands have much in common with Anim8or (thanks Steve for allowing the use of Anim8or buttons!). While Edit Mode and selection is enabled (with Select, or Drag-Select tools), left mouse click selects, right click adds to the selection, middle button toggles selection. Left-clicking an empty area deselects all. The menu is made to resemble Anim8or's menu and most of the similarly named items do similar actions. Though the menu is self explanatory with only a few items needing instructions, I'll list all the individual items for the sake of completeness:

FILE

  • New - Creates an empty .an8 file, discarding the previously loaded file
  • Open - Open an .an8 file, discarding the previously loaded file. After being parsed, the file is closed, making it available for other applications. The subsequent editing is done on a copy in the memory
  • Save - Saves the currently edited file, overwriting the original
  • Save As - Saves the currently edited file with a different name, keeping the original file intact.
  • Save Image As - Makes the contents of the current workspace into an image (jpg, bmp, gif, png or tiff)
  • Configure - Sets persistent application variables: Background Color (allows setting a custom background color for the workspace), Anim8or File Path (selects the path to Anim8or.exe for quick launch from within Terranim8or), Most Recently Used Files (quick launch for the most recent four files)
  • Exit - Quits Terranim8or

EDIT

  • Cut - Deletes the selected component(s) from the current object or scene
  • Copy - Copies the selected component(s) from the current object (or scene)
  • Paste - Pastes the selected component(s) into the current object (or scene)
  • Delete Object - Deletes the current object with all its components
  • Delete Scene - Deletes the current scene with all its components
  • Rotate > Rotate None - Resets the selected component(s) to face the screen
  • Rotate > Rotate custom - Allows entering numeric values for the orientation of the selected component(s).
  • Rotate > Rotate X/Y/Z 90 - Rotates the selected component(s) with 90 degrees counterclockwise around X/Y/Z axis
  • Scale > Scale Custom - Scales the selected component(s) with the specified amount (uniform and non-uniform scale)
  • Scale > None - This command is available only in scene mode and resets the selected component(s) to its (their) original size
  • Locate > Center about origin - Moves the selected component(s) in the origin of the workspace (object, or scene)
  • Locate > Locate Custom... - Allows entering numeric values for the location of the selected component(s). Optionally, the current coordinates can be shifted with a specified amount. For multiple selections, there is an option to shift each component with a specified amount more than the previous one. That generates equally spaced arrays of objects for components originally located in the same place. It works for any or each coordinate axis simultaneously.
  • Controller Script > Visibility / Scale / Position / Orientation / Color / Fov / Active / Morph - Opens the Script Editor to edit the selected scene element's controller script. It serves for creating, editing and erasing controller scripts, also for evaluating the current value of a controller.

MODE

  • Object - Switches to Object Mode
  • Scene - Switches to Scene Mode. It creates an empty scene with a default camera, if the file hasn't already a scene.

OBJECT

  • New - Creates a new empty object (like in Anim8or)
  • "obj_name" - Makes the object named "obj_name" current, for editing (like in Anim8or)

SCENE

  • New - Creates a new empty scene with a default camera and ground grid (like in Anim8or)
  • "scene_name" - Makes the scene named "scene_name" current, for editing (like in Anim8or)

VIEW

  • Materials - Shows / hides  the Material Editor. Allows apply and copy / paste operations for materials from / to any location in the file: between file and object materials, in the same object, between different objects. Click between the material buttons and drag to slide the editor if there are too many materials. Editing the materials is not yet implemented.
  • Wire, Flat, Smooth - The same as in Anim8or
  • Front, Left, Right, ..., Ortho, Perspective, Camera - Changes the view point, like in Anim8or
  • Reset - Resets a modified view to its default
  • Options > Bounding box - Toggles the visibility of the selection bounding box
  • Options > Flesh Bounding Box - With this option checked, a bounding box appears for approx. 0.2 seconds when a selection is made, allowing to check if the right object was selected. Then the bounding box vanishes, but the object continues to be selected.
  • Options > Antialiasig 8(16) passes - Sets the number of rendering passes for antialiasing. The 16 passes option gives a higher quality at a roughly double rendering time.  
  • Options > Show Backface - Both sides of a face are rendered. This is the default. To increase speed, for huge models, disable it!
  • Options > Output Normals - The same as in Anim8or. Terranim8or, like Anim8or, doesn't use normal information stored in the file.

BUILD

  • Group, Ungroup - The same as in Anim8or
  • Convert to Mesh - The same as in Anim8or (presently effective only for subdivisions)
  • Terrain > From Height map... - Generates a terrain from a height map (gray-scale, or color image). The terrain has user specified size and resolution and is generated with texture coordinates.
  • Terrain > Generate - Builds a terrain with custom user settings. Available types: regular, fractal, turbulent, displaced and island. The terrain sequences allow for simulation of ocean and flowing water.
  • Terrain > TAN8 UV Mapping - Generates special UV coordinates for terrains, tailored for each individual terrain. Works with special TAN8 textures.
  • Terrain > Create TAN8 Map - Makes a special texture from four supplied images for terrain texturing. Works with TAN8 UV Mapping.
  • Subdivide > Rounding (tension 0) / Flat (tension 1) - The same as Anim8or's subdivide with tension 0 and 1. It works for meshes and subdivisions, not for parametric components.
  • Make Triangle Faces - Converts the selected mesh(es) to triangle faces, without affecting the normals
  • Displace - Moves the vertices of a mesh (or subdivision) according to the color information in the associated displacement map. A neutral gray  - RGB(128, 128, 128) will not modify anything. A darker color displaces the mesh inwards, a lighter shade extrudes with a maximum amount specified by the user. The mesh must have texture coordinates (faces missing texture coordinates won't be displace) and has to be very well tessellated (subdivided multiple times) to display the details of the map!
  • Simplify Mesh - Makes polygon reduction on meshes to a desired polygon count, or a limiting surface error. 
  • Primitives > Circle - Makes a perfect circle spline. It can be done into an ellipse with the non-uniform scaling tool
  • Primitives > Plane - Makes a plane with user set divisions and size.
  • Remove Roll - Removes the roll from the selected component's orientation, without disabling roll as the component's property
  • AntiAliasing - renders the workspace a specified number of times (set in View -> Options) to eliminate jaggies from the image. The antialiased image stays like that until the next image update. If you intend to save it, do it before any other action. In Edit mode, even a click in the workspace updates the image and the antialiasing is lost!
  • Cube Environment Mapping - instantly creates a cube map centered in the selected scene object, textures the corresponding object and saves the six texture files for the cube map in the file format specified by the user
  • Add Current Object - Adds the currently selected object (with all of its components) to the current scene, in the origin
  • Add Current Object 'n' times - Adds 'n' instances of the currently selected object (with all of its components) to the current scene, all of them in the same location and being selected
  • Add Target - Adds a target in the origin of the scene
  • Add Camera - Adds a new camera to the scene
  • Add Light - Adds an infinite light 
  • Environment - Sets scene environment parameters: background color, ground grid, fog 

PLUGINS

  • If Terranim8or finds plug-in files at start-up in the current directory, loads them and a "Plugins" menu is created. By default, Terranim8or installs the plug-ins in this menu, but the plug-ins are free to install themselves in a custom menu.

ABOUT

  • Terranim8or - Version information
  • OpenGL Info - Displays OpenGL related information from the host computer.

TOOLBAR BUTTONS - LEFT SIDE BAR

  • View Mode - The workspace can be scrolled, scaled and viewed from any direction, but without touching the objects
  • Edit Mode - The objects can be selected for editing. The view point is restricted to that offered by the View menu. To access objects outside the current viewing window, switch to other views. Alternately, switch to View Mode, scroll the view with the Move button so that the object gets visible (no rotation should be done), then switch back in Edit Mode. If a rotation was done in View Mode, it will be reset automatically when switching to Edit Mode.
  • Select, DragSelect, Move, Rotate, Scale, Non-uniform scale - The same as in Anim8or

TOP SIDE BAR

  • New, Open, Cut, Copy, Paste do the corresponding menu actions
  • The button with the Anim8or icon launches Anim8or with the file currently edited by Terranim8or, updated with the latest changes made to it. That is like transferring the contents of Terranim8or's workspace into Anim8or. NOTICE: 1. The location of Anim8or's executable file has to be known by Terranim8or (Previously set in File -> Configure -> Anim8or path). 2. This operation involves silently saving the file at the current editing stage, i.e. overwriting the original.
  • Materials button shows / hides the Material Editor.
  • Shading selectors are the same as in Anim8or
  • The Flash Bounding Box button toggles the "flesh box" mode. In this mode, the bounding box appears for approx. 0.2 seconds when a selection is performed, offering feed back on the object being selected. Then the bounding box disappears, leaving the object selected. This mode is useful in cases when the bounding box is in the way (like for fine positioning) with the advantage of confirmation of the right selection.
  • Antialiasing button issues Build > Antialias command, described above.
  • The VCR style buttons control animation playback in scene mode. The Play button resumes the animation from the current frame, unlike in Anim8or where it starts over from frame 0. In the right side of the status bar it is displayed the current frame number.



Known issues

  • The file reading progress bar (and percent indication) may freeze during file loading, especially when reading huge files on a system already under heavy load (more other open applications). This is due to windows' messaging mechanism used for updating the progress indicator, which fails if overloaded (that is true with many other applications also). It DOES NOT mean that Terranim8or is hanging, just can't manage to show the progress. Have patience, the parsing is going on!
  • Exiting Terranim8or (File > Exit, or closing the window) and File > New / File > Open are executed immediately, without warning to save the current file. You have to remember to save the file (if you want to) before Terranim8or discards it! This will change in the future, but for now it is better this way: testing means discarding and loading a lot of sample files and the popping window always prompting to save the current file would be very annoying...
  • The bounding box for groups can have wrong size if a component has been rotated before grouping. Splines do not have bounding box at all.
  • Terranim8or's "Ortho" view does not provide accurately the same view as Anim8or's (I have to do some more detective work). Also the default lights (in the object editor and in the scene) are not exactly Anim8or's lights - I'm trying to have them close...



Bug reports

When reporting a problem, please be explicit regarding the nature of that problem. A statement like "Terranim8or doesn't work for me" it's of little help, because it gives no clue about what is going wrong! Try to give instructions on how to reproduce the bug. Specify your Operating System, graphics card and the OpenGL version you are using (it can be known from the About -> OpenGL Info menu). Do not send reports about features that are not currently implemented! For example, a report stating that two materials with different brilliance values are rendered identically has no relevance, since brilliance is not an implemented parameter... On the other hand, if an object appears to be placed, or oriented differently in Terranim8or compared to the same scene in Anim8or, that would be a problem, because positioning is implemented!

What should be tested? Anything you like to...
- File loading and file saving (compare if Anim8or sees the saved file exactly like the original one)
- How does selection perform? (For example, my office system shows a strange behavior - it does the selection OK, but while the mouse button is pressed, a previous image is displayed - releasing the button, the current image reappears. Drag-select works as expected.)
- Test the various menu commands and the tools, edit scene setups, play animations
- Test for memory leaks only if a reliable utility is available. The displayed memory usage in XP's task manager is of no relevance. I have checked and eliminated memory leaks in the development environment, but surprises can arise...


Download instructions

CONDITIONS OF USE:
Terranim8or 7 is free for use and anything you create with it is your property. I encourage users to provide feed-back in order to make this tool better!

Download Terranim8or v7: Terranim8or.zip (version 7.10.1)

Plug-in files: 
(Unzip them into the same directory with Terranim8or.exe)

Download the Boolean Operations plug-in: Booleans.zip Performs boolean operations on meshes
Download the CubeMap plug-in: CubeMap.zip Generates a file to render in Anim8or a cube environment map 
Download the Starry Background plug-in: StarryBackground.zip
Download the Fire Effect plug-in: Fire.zip  
Download the Explosion Effect plug-in: Explosion.zip  
Download the Spherical / Cylindrical UV mapping plug-in: SphericalCylindricalUVmapping.zip
Download the Particle Trail plug-in: ParticleTrail.zip
Download the Noise Modifier plug-in: NoiseModifier.zip
Download the Camera Quake plug-in: CameraQuake.zip

Terranim8or is a Windows application. In order to get working, it needs some common Windows library files (which are already on your system if you are able to run previous Terranim8or versions) and other .dlls (which you might not have), available below for download.
If your operating system is Windows XP with Service Pack 2, you should try downloading only Terranim8or.exe, because there are good chances that the further listed files are already on your machine. However, if Terranim8or cannot run, a message will inform you about missing dll files. Actually, the message may prompt for the first encountered missing file. After downloading it, when retrying, it could indicate an other missing file - Windows is not smart enough to tell in the first place all the dependencies of a native C++ application...
If you are prompted for missing dlls when trying to run Terranim8or v7, download the missing files listed below, unzip and place them in the same directory with Terranim8or:

MFC71.dll         (zipped) if that is missing from your computer
MSVCR71.dll    (zipped) if that is missing from your computer
MSVCP71.dll    (zipped) if that is missing from your computer

All the above files (zipped together for easier download) if all of them are missing...

Once having them on your computer, you will no longer need to download them again when Terranim8or updates arrive.
I'll appreciate any feedback on this matter (whether you needed or not to download the dlls) to decide about the release version.