                            ---------------
			      LithUnwrap
                              Version 1.3
                            ---------------


DESCRIPTION
===========
LithUnwrap is an easy to use, UV coordinate editor for Windows.  
Use it to edit UV coordinates, unwrap models, or export UV maps 
to bitmaps for painting.

LithUnwrap is donateware.  It is free for personal or commercial use, 
however if you find the program helpful in any way, please send a 
donation via www.PayPal.com to bbolthou@bigfoot.com.  Donations will 
go toward future developments and better web hosting.

See HISTORY.TXT for important changes and updates.


RECOMMENDED
===========
 - 3D hardware-accelerated graphics card.
 - 16-bit or 32-bit display mode setting.
 - DirectX 8 or later.   See: www.microsoft.com/directx
 - OpenGL 1.1 or later.  See: www.opengl.org, www.glsetup.com


CONFIGURATION/INFO
==================
See unwrap.ini and unwrap.log for more details.


SELECTING
=========
In order to UV map, move, scale, rotate, flip, expand, collapse,
or to perform most operations, vertices must be selected first.

Two basic ways to select vertices is to drag a box around them or 
click on them.  Any selected vertex is then highlighted in red.

Once a vertex is selected, it can be moved by clicking in the 
rectangle that outlines the selection and then dragging it.  

You can optionally use the SHIFT and CTRL keys to add or remove 
vertices to/from your selection.


TOOLBAR BUTTONS
===============
Reset All			- resets the entire scene.
Reload All Textures		- reloads all textures from file.  This is 
                                  useful when working with a paint program.
Save UV Map to a Bitmap
Copy UV Map to System Clipboard
Rectangle Selection
Lasso Selection
Soft Selection                  - used with moving vertices.
Select Mode			- use rectangle or lasso selections.
Move Freely			- pan the view in UV space.
Zoom Freely			- zoom the view in UV space.
Zoom Region			- zoom to a specific region in UV space.
Select By Vertex		- select only vertices.
Select By Face			- select only faces.
Select By Group			- select only groups.
About


UV MAPPING
==========
"Select by Face" or "Select by Group" must be checked to apply 
a mapping to the selected faces.

camera      - Map the selection from the camera.
decal       - Map the selection from one side.
face        - Map the selection from each face's normal.
planar      - Map the selection from two sides. 
box         - Map the selection from six sides. 
cylindrical - Map the selection from a cylinder.  
spherical   - Map the selection from a sphere. 


Scaling Options
---------------
Scale non-uniformly - This scales the mapping so it non-uniformly fits  
                      within the red selection box.

Scale to selection space - This scales the mapping so it uniformly fits 
                           within the red selection box.

Scale to mapping space - This scales the mapping so it uniformly fits 
                         within the mapping space of 0,0 to 1,1.

Apply no scaling - This does not scale the mapping at all.  Note that 
                   the mapping will still be uniform.


Gizmos
------
There are no UV mapping gizmos currently available yet, however the 
camera itself may be used as a planar gizmo.  Follow these steps to 
get a distortion free UV map of a face:

1. Select the face in the 3D preview window.
2. Right click Align Face->Camera.  Click Apply.  Click Close.
3. Right click Map View.

If you do not want to rotate or move the model, then you can 
use Tools->UV Mapping->Face.


FACE MAPPING 
============
Each face is planar mapped using its face normal, and uniformly scaled.  
This will produce zero distortion UV maps, however all faces will be
detached.


Packed
------
This will layout the detached faces so they are tightly packed into 
a square.

Overlapping
-----------
This will layout the detached faces so each face is uniformly scaled 
to the mapping space of 0,0 to 1,1.



BOX MAPPING
===========
Box mapping arranges the faces to the following layout:

 Left  - Top    - Front  
 Right - Bottom - Back

By checking the 'Separate by group' option, you can change
the layout according to group.


Separate by group
-----------------
Side by side - This arranges the faces to the following layout:

 (group 1)   (group 2)  ...etc.
 L - T - F   L - T - F 
 R - B - B   R - B - B 

This is useful if you are planning to have all UV maps assigned
to the same texture and do not want any groups to overlap.


Overlapping - This arranges the faces to the following layout:

 (all groups)
 L - T - F  
 R - B - B 

This is useful if you are planning to have each group assigned 
to a different texture.  They will not share the same texture space,
therefore it does not matter if the groups overlap.


PRIMTIVES
=========
Up to 10 primitive models can be created within LithUnwrap: a plane, 
a box, a cone, a cylinder, a sphere, a geosphere, a pyramid, a prism 
(extruded isoceles triangle), a tube, and a torus.  

Upon creation, each model is automatically applied one of the available 
UV mappings, with exception to the tube and torus.  Their UV mappings are 
auto-generated upon creation.


MENU OPTION: VIEW
=================
Click View->Show->Vertex Boxes to draw vertex drag boxes around 
each vertex.  You can turn them off to improve drawing performance.

Click View->Show->Grid to display gridlines in the Editor window.  
The grid resolution is in UV space, which can be changed in 
Options->Preferences.

 NOTE: The Editor window will always be displayed at 1:1 aspect 
       ratio.


SCALING
=======
To scale UV coordinates freely, click Edit->Scale->Free.  To scale
the selection, click and drag one of the green corner drag boxes.

To scale the selection uniformly, click Edit->Scale->Arbitrary...
and enter the same value for U and V.

The S key can be used to quickly enable Free scaling.


MODIFY GROUPS
=============
In order to assign selected faces to a group, "Select by Face" or 
"Select by Group" must be checked.


DELETE GROUPS
=============
Note that deleting any group will permanently delete the associated 
geometry as well.  Use "Remove..." under Modify Groups instead if
you want to remove the group name and not the geometry.


HIDING/UNHIDING
===============
If you have a large and complex model, you can hide individual groups 
to improve drawing performance.

After a group is hidden, it will not be listed in the "Select by Name"
listbox.  The group must be unhidden first before it can be selected
again.

NOTE: If a face is hidden, you will not be able to select it in the
      3D preview window.


MERGING
=======
Click File->-Model->Merge... to merge geometry from file into the 
current scene.

Specific info for Tread Marks:
To merge LWO and LUV files, the option "Autoload LUV with LWO" must 
be checked under the Preferences menu.  Also, the two files must have
the same name (e.g. mymodel.lwo, mymodel.luv) and be in the same 
directory.  


EXPAND/COLLAPSE
===============
Expand/collapse are helper functions for scaling.  Expand scales
the selection to the maximium UV space of 0,0 to 1,1, while collapse 
scales the selection to a single point.  Note that collapsed points 
cannot be expanded afterwards because they are dimensionless.

Expand All - scales the selection uniformly to the UV space of 
             0,0 to 1,1.

Expand Horizontal - scales the U coordinate of the selection non-uniformly 
                    to the range of 0 to 1.

Expand Vertical   - scales the V coordinate of the selection non-uniformly 
                    to the range of 0 to 1.

Collapse All - scales the selection to a single point.

Collapse Horizontal - scales the U coordinate of the selection to 
                      a single point.

Collapse Vertical   - scales the V coordinate of the selection to 
                      a single point.


INFORMATION
===========
z-buffer - The depth of the scene.  Note that large models
           over 1000 units can cause flickering z-buffer artifacts.
           Try scaling down your model to avoid this.

bounding box    - The min/max values of the axis-aligned bounding 
                  box of the entire scene in 3D space.
bounding radius - The radius of the bounding box.
groups          - The number of groups in the scene.
polygons        - The number of n-sided polygons in the scene.
triangles       - The number of triangles in the scene.  
vertices        - The number of indexed vertices in the scene.


UNDO/REDO
=========
There are 10 levels of undo available.  You should be able to undo 
all 2D and 3D operations.

 NOTE: If you experience hard drive slow downs when loading very 
       large models, see Options->Preferences->Undo for options 
       to limit storage.


BONES
=====
See HISTORY.TXT


MATERIALS
=========
See HISTORY.TXT


ASSIGNMENT
==========
See HISTORY.TXT


WELDING
=======
To weld UV coordinates, click Edit->Weld.  The tolerance value is the 
minimum distance necessary for welding between any two UV coordinates. 

Weld = 0 < distance < tolerance

All values are in UV space.


ALIGN FACE
==========
To align a face to a major axis or to the camera, "Select by Face" must
be selected.  If you select more than one face, the alignment will be
the averaged sum of all selected face normals.


PICKING
=======
In some cases, it might be easier to select faces from a 3D perspective
view instead of a 2D view.

To select faces in Preview Mode, enable any Wireframe rendering type:

 Wireframe Lines
 Wireframe + Flat
 Wireframe + Smooth
 Wireframe + Flat + Textured
 Wireframe + Smooth + Textured

Then toggle the "Select Faces" menu option in the Preview Mode floating 
menu.  The S key can also be used to quickly toggle this feature. 

After you have selected your faces, toggle "Select Faces" again to 
lock your selection.

To deselect everything, click in empty space.

NOTE: If a face is hidden in the Editor window, you will not be able 
      to select it in the Preview window.


SHORTCUT KEYS
=============

  Ctrl+Z = Undo
  Ctrl+R = Redo
  Ctrl+A = Select All

 Editor Window
 =============
  Q = select mode
  W = move freely
  E = zoom freely
  R = zoom region

  M = toggle visible material 
  S = scale selection
  H = hide selection
  N = select none

 Preview Window
 ==============
  P = 3D perspective view
  I = 3D isometric view
  F = front orthogonal view
  B = back orthogonal view
  L = left orthogonal view
  R = right orthogonal view
  T = top orthogonal view
  Y = bottom orthogonal view

  SPACEBAR = toggle auto-rotating camera


TEXTURES
========
For best performance and compatibility, there are a couple of rules
you should follow when loading textures:

1. Use textures that have dimensions that are powers of 2.
  (e.g. 2^n = 64, 128, 256, 512, etc...)

2. Use square textures. (e.g. 128x128, 256x256, etc...)

3. Avoid using very large textures.  Some 3D cards may not support 
   dimensions larger than 256x256. (e.g. older Voodoo cards)


SAVE UV MAP
===========
You have a couple of options when saving your UV map to a bitmap:

1. Black and white - all groups will be outlined in white and 
                     drawn on a black background.  If Fill is 
                     checked, the groups will be filled with white.

2. Color           - all groups will be outlined in color and 
                     drawn on a black background.  If Fill is 
                     checked, the groups will be filled with color.

3. Color and outline - same as Color, except the groups are outlined
                       in white.  If Fill is checked, the groups will 
                       be filled with color.  Typically, this is only
                       useful when the Fill option is checked.

NOTE: When using the Fill option, it is best if no groups overlap
      each other, otherwise some faces may be hidden.


GAME FORMATS					VERSION
============					=======
LUV - Tread Marks				   -
PRM - Re-Volt					   -
MDL - Quake 1                                      6
MD2 - Quake 2					   8
MD3 - Quake 3 Arena				  15
NOD - Vampire: The Masquerade - Redemption         7
SMF - 4x4 Evolution			           4
SOD - Star Trek Armada 1/2                   1.6, 1.7, 1.8, 
                                         1.9, 1.91, 1.92, 1.93
MDL - Serious Sam                                 10
ACT - Genesis3D					 0.241
3DO - Jedi Knight: Dark Forces 2                2.1, 2.2
L3D - Black & White                                -
MDL - Half Life                                   10
POF - Freespace 1/2                              21.17
OOF - Descent 3					 23.00
PEO - Homeworld                                  1026
SKN - The Sims					   -
MDC - Return to Castle Wolfenstein		   2
MDL - 3D GameStudio                                -
NDO - Nichimen Nendo                            1.0, 1.1

If you would like to see a game format supported, send me
the file format specification and I will see what I can do.


GRAPHIC LIBRARIES
=================
LithUnwrap uses the JPEG Software Package (Release 6b) from the 
Independent JPEG Group to read JPG files.  A file named uvlib.dll
should be located in the same directory as the main program.


CONTACT
=======
Author: Brad Bolthouse
 Email: bbolthou@bigfoot.com
   URL: http://www.geocities.com/lithunwrap


FINAL
=====
You may freely distribute this software, without permission from 
the author, on the conditions that no fee is charged for distribution
and that all files are not removed or modified in any way.

The enclosed software is provided "as is".  The author assumes no 
liability for damages, direct or consequential, which may result 
from the use of this software.

All trademarks and trade names are properties of their respective 
owners.

Copyright  2001-2002.  All Rights Reserved.
