NB this documentation style mercilessly ripped off from Chris Colefax of "The Include Files" fame (with permission, albiet after-the-fact). I hope that having a familiar (or "standard" format will make the documentation even more readily comprehensible.

This program (and the programmer) owes much to it's creation. Obviously without the POV-Ray teams efforts, or those of Nathan Kopp and Ronald L. Parker (authors of uvPOV and Superpatch POV respectively), I'd never have started the project. Aditionally Mick Hazelgrove and "Uncle" Ken Tyler have helped with testing, reporting problems, ideas, and enthusiasm. Chris Colefax and other members of the POV-Ray community have also tried to increase my knowledge of "3D techniques" necessary to making this program useful. Finally you - quite possibly. Although development has slowed quite dramatically (largely to enable me to have a life in between all my "projects") the program is far from finished as far as I'm concerned - and if there's a change you'd like made (or a feature added) then pipe up - within its limited scope I'd (obviously) quite like the program to be as useful as possible...

Cliff Bowman

INSTALLATION

QUICK START

OPTIONS

TIPS

FUTURE PLANS

COPYRIGHT AND LEGAL INFORMATION

CONTACTING THE AUTHOR

DEVELOPMENT HELL (HISTORY)

Copy the OBJuvPOV.exe file where you want, and run it from there. Alternatively (if you have the "complete" .ZIP file) run the setup.exe program provided. this will also create a shortcut in the "Start...Programs" menu

Try running it... select a .OBJ file and press convert. Two files will be created, in the same folder as the .OBJ file and with the same name but the extensions .POV and .INC. The .INC file holds the actual mesh(es) and the .POV file is an example scene file using the .INC.

If you have any trouble seeing complete folder and/or file names - try resizing the OBJuvPOV window. The controls resize accordingly.

*WARNING* At present OBJuvPOV will ask before overwriting the FIRST file which already exists... it won't ask about any later ones. Be careful not to lose any work!

You can process several files at the same time, provided that they are in the same folder. Simply select all the files that you want to convert and OBJuvPOV will cycle through, converting each one as it goes.

There are now 4 sections in the "Options" Dialog:

GENERAL
These options are currently unselectable because I haven't written them yet.

POV Export
Here you can currently select from a few output "formats". More options to come...

OBJ Export
Nothing here yet - .OBJ Export has yet to be implimented.

OBJ Import
This is where you select Degenerate Triangle Removal (or not, as the case may be).

STRANGE "EXTRA" OBJECTS
Some programs (for example, Poser 4) occasionally export odd faces which aren't apparent in the original model. My best guess as to what these are, judging by those I've encountered thus far, is that they're used internally within the originating program to help "position" the model. For example, an item of clothing may have "invisible shoulders" which help the originating program to bend and twist the clothing to fit a posed character.

Depending on whether you have the originating program or not, there are a couple of ways of dealing with these "extra" items. If you can re-produce the .OBJ by de-selecting the unwanted objects during the export process then you'll end up with smaller files which convert, parse, and probably render quicker. If that's not an option then perhaps setting the material used by those items to completely transparrent might work - as long as the material is a unique one and not, say, the same material as used by the clothing object itself, or another object in the .OBJ file.

DIFFERENT OBJECTS BUT THE SAME MATERIAL
Some .OBJ files, based on what I'd call "unfinished models", contain multiple objects which SHOULD have different textures - but don't have different material names applied to them in the .OBJ file(s). I've come across this in a situation where a young lady's hair and ear-rings used the same material - far from ideal.

At present there's no way around this but to re-export the .OBJ file as two seperate files and re-combine them in POV-Ray (using the correct texture for each generated .INC file) or to edit the .OBJ file changing the material name wherever required (not recommended). A programmed response to this situation is under consideration (having far more tetures, one for each object name & material name combination). I'm concerned that this might be somewhat unweildy so coments would be appreciated.

POSER 4 BODY PARTS SHOW THROUGH CLOTHING
The standard technique for dealing with this in Poser is to make the body part invisible - but invisible body parts still get exported to .OBJ files with their original texture (visible!). If possible, deselect the part/parts when exporting.

There *were* numerous future plans for this program. However I'm working on a new program in C++ called "OBJuvMOD" which should incorporate all of the features of OBJuvPOV and (hopefully) a whole lot more. Additionally, it is hoped that by writing it in C++ it will be much more transportable - so there could yet be Linux, and possibly even Macintosh variations at a later stage. Since that's a long, long way in the future (depending on, at the very least, time and intelligence on my part) I've left the list of immediate hopes for OBJuvPOV in this document (partly to remind ME of some of the improvements to make when I re-code it as part of OBJuvMOD).

PROBABLE UPDATES to OBJuvPOV after incorporation into OBJuvMOD

• Support for Poser .mtl (material description) files
• Ability to include Chris Colefax's UV macro (TriMap.mcr) within the body of all TriMap export files - this would increase filesize but make for faster renders.
• Ability to group all triangles into 1 mesh (to minimise parse time, memory usage, and file size where the model uses just 1 texture)
• Direct support for Animating Batches (creating several .INC but just one controlling .POV for a numbered sequence of .OBJ files
• Ability to set rounding parameters - should reduce .INC file sizes
• Move the huge "History of Development" section of this document to somewhere more obscure :). Probably delete quite a lot of it since few people have seen the various stages to date anyway (partially done).

MORE SPECULATIVE UPDATES

• Export to compressed mesh format variant of TriMap version .INCs, co-incidentally making the mesh available for various transformations
• Attempt to replace missing normals to prevent (or at least minimise) resorting to flat triangles
• Recalculate all normals in an effort to correct meshes which have some (or all) normals reversed - resulting in apparent "holes" in the mesh(es)
• Ability to NOT texture meshes in .INC but leave that to the user in their .POV file(s)
• Ability to #declare seperate name for each group (to make the above easier where a model uses multiple textures)
• Possibly increase number of textures so that each texture in the .POV file is named not just after the original "material name" but also after the group it applies to. It's turning out that some completely different "objects" within a Wavefront model - with different colouration - are flagged as using the same material (example: Earring 'props' and hair 'prop'). Needs considering
• Better progress reporting (more informative during batch/animation processing)
• Support for non-Windows platforms. Very speculative, but the program MAY be converted to JAVA, C, or C++. Quite unlikely now that I've resumed having a life.
• Provide a mechanism for OBJuvPOV to execute uvPOV after each file in a batch (or animated batch) is converted, and optionally delete the .POV and .INC files after rendering. Best suited to fast machines with a desire to keep disc space usage to a minimum. Alternatively provide a mechanism for POV to call OBJuvPOV before parsing the file(s) created by OBJuvPOV (less neat IMO - comments?)
• Misc. cosmetic changes (E.G. toolbar, statusbar, ability to use user-defined graphic for progress indicator, etc.)
• Program speed optimisations
• Provision for writing back "cleaned-up" .OBJ file/s (degenerate faces fixed/removed, any "normal" corrections OBJuvPOV has managed, etc.)
• Provision for checking (and removing) duplicate faces - a problem I'm told has been seen in .OBJ files but which I haven't knowingly encountered yet (so may be rare)
• Support for .OBJ specifications not used by Poser4 (Possibly. Maybe)

The OBJuvPOV executable file, all documentation, and the source for such, are Copyright 1999 by Cliff Bowman. Portions Copyright by Microsoft Corporation. Full permission is NOT granted to the user to modify the executable or documentation for his/her own use. Permission is granted to use the program free of any charge for any commercial or non-commerial application with no other restriction or requirement beyond the laws of your region (e.g. it's almost certainly illegal to bludgeon your neighbor to death with a copy of OBJuvPOV, etc etc).

OBJuvPOV from the first official release (V1.0) onwards may be bundled with or without other software on CD-ROM collections, Bulletin Board Systems, Internet WWW and FTP sites, and other file archives, providing that all associated files, including documentation and samples, are included unmodified. I would also request that persons intending to distribute OBJuvPOV in this manner or otherwise would first contact me to ensure that they are in possession of the latest available version.

Further, no restrictions of any sort are placed on the usage of the exectutable file itself (OBJuvPOV.exe), and scene files or images created using OBJuvPOV remain entirely the property of the user or users who have created them (with obvious exceptions if the copyright of the source .OBJ/s has been exerted by the originator - OBJuvPOV can not be used to subvert copyrights). I claim no liability or responsibility for damages or loss resulting from usage of the program, or any part of the package. I make no guarantee that the program will do anything BUT produce such damage/loss, however well it works for me (it's primary user).

Created by Cliff Bowman, 23 August 1999
Updated 26 August 1999: Transferred VBA project to VB5
Updated 28 August 1999: Fixed Degenerate Triangles problem. Fixed problem where .OBJ faces had no UV co-ordinate data.
Updated 28 August 1999: Created single executable (no reliance on external .OCX files).
Updated 28 August 1999: Added simplest possible error handling routine. Unhelpful, unfreindly, it's there JUST to prevent crashes while I concentrate on conversion issues. Fixed 'subscript out of range' bug where excessive verteces (5 or more) were encountered. The first such is now reported (if no other unsupported feature has been reported) and all verteces after the fourth ignored.

Updated 29 August 1999: Added drive, folder, and file boxes to main form to make picking files easier until I do a "proper" file interface. Added .INC naming bug in POV file at the same time...

Updated 29 August 1999: Fixed INC naming bug. Misc interface tweaks. Added simple batch converting (just select al lthe files in the current folder that you want to convert). Added VERY basic file overwriting code - you can choose to overwrite all or no files once the program encounters an existing output file (or one that just happens to be named the same). Added extent of .INC mesh to .POV output, and simple light and camera calculations based on these to centre the mesh in the display window. Changed progress graphic to an unfinished "Concrete Jungle: The Hunt" scene I'm working on, which better shows using uvPOV capabilities (i.e. as more than just a renderer). Concrete Jungle: The Hunt uses Chris Colefax's "City" and "Galaxy" Include files, Poser models and textures, and skin textures from the Poser Forum.

Updated 30 August 1999: Fixed Cancel button resize/disapoearing problem and "Degenereate Triangles" warning label reposition issue. Negated Min and Max Z in .POV output routine to match .INC output. Also Corrected "Camera" and "Look_At" co-ordinates. Added "Obese Face" export.

Updated 1 September 1999: Increased supported face input and output routine from 4 to 40 verteces. This is currently excessively memory-hungry (using temporary storage space for 40 verteces for every face while calculating, regardless of how many are used) but the new triangle output segment deals with *all* supported face verteces in a loop (simpler than the previous solution for 3/4 vertices which had seperate code for the second triangle).

Updated 2 September 1999: Drastically reduced the number of formatting elements in .INC output (mainly spaces). This has made the file much less readable by human beings but considerably smaller - important for even fairly modest animations.

Updated 4 September 1999: So what happened on the 3rd? Seems I took a day off. Anyway, fixed "No Usemtl" bug and provided identical error check for "No Groups". Reduced POV output file size further. Tidied and enhanced the minimal error reporting that OBJuvPOV has at present (by filtering virtually all menu/button commands through a single error checking routine). Added check for missing normal(s) in source .OBJ (although OBJuvPOV currently doesn't do much about them).
Updated 5 September 1999: Added ability to load and save options in a private .INI file (showing above all my reluctance to mess with the registry - which is generally more hassle than it's worth, IMO). Mesh type (despite lack of actual mesh 2 support) and current file locations are the first "options" to be saved when you exit the program and recalled next time you load it. Drastically reduced memory usage for all faces containing fewer than 40 vertices - and at the same time raised the "Obese faces" vertex count limit to 32000 (a number hopefully sufficiently obscene that it won't be encountered - the most verteces I've seen in one face so far is 26).

Updated 6 September 1999: Fixed start-up sequence so that main form appears centered from the start (no "flash" of appearance elsewhere on the screen). Neater. Added new attempt at mesh2 export - with no more success than my first attempt (flawed UV mapping).
Updated 7 September 1999: Fixed erroneous "missing normal" problem in mesh export which was causing some triangles to be flat where they could, in fact, be smooth. Added check for whether OBJuvPOV is compiled, or running within the VB development envirnment, and only activate certain Windows functions (mainly "WindowsMinMax") if compiled - this makes debugging easier.
Updated 9 September 1999: Vastly improved "progess image" display. Added "Priority" to list of options saved and re-loaded upon exit and start-up. Changed save routine to only save if the OBJuvPOV session isn't unloading during a conversion (which is now treated more properly as "abort! I've changed my mind! Don't do that!" AND avoids a Visual Basic bug where non-visuble drive and folder controls return erroneous drive and path info). Thanks to Nathan Kopp checking out one of my mesh2 samples and point out the error in it, I've now got mesh2 export working. I've also optimised the export slightly for file size - and my mesh2 test files are less than half the size of the same .OBJ's converted to mesh syntax. Neat format! Degenerate triangle removal can now be turned off in the options dialog (as I work towards an export where the meshes are avaialbe for deformation within POv-Ray - where it can be important to leave degenerate triangles in for key-framing).

Updated 1 September 2000: Version 0.0.14. In recent days I've added (and then improved) code to include the #version directive required by version 0.5 of MegaPOV. I've also corrected a previously unknown bug where usage in some countries (notably France) resulted in OBJuvPOV using a "," instead of a "." as the decimal seperator for camera position and lights - very bad! It may be technically correct for the country, but made the program harder to use than it should have been for anyone in such an area. Basically they had to edit the small .POV file and replace "," characters with "." characters. Fortunately the .inc file produced in mesh2 format was unaffected by this. I've also extended the error reporting further in the hopes of getting some feedback if there are any .OBJ meshes which still fox OBJuvPOV - please people, if it isn't working, e-mail me. Even though I'm working on a faster replacement program, I may just be able to improve this one quite easily if there's a need for it.

If you wish to contact me with bug reports, bug fixes, criticisms, comments, suggested improvements, example .OBJ file (that worked or didn't), questions, etc. you can reach me by email at:

who3d@geocities.com

POV-Ray^TM and Persistence of Vision^TM are registered trademarks of the POV-Ray Team^TM