geopy/README.md

# geopy

Python tools for manipulating .geo files, and Blender add-on for exporting .geo files.

# Blender Add-On

The Blender add-on allows you to export .geo files.

## Installing the Add-On

1. Download geopy-v0.2.1.zip
2. In Blender open "User Preferences" then select the "Add-ons" tab.
3. Click the "Install Add-on from File..." button and select the downloaded zip.
4. Enable the add-on and click the "Save User Preferences" button.

## Using the Add-On

1. Select the meshes to export in object mode.
2. From the menu select File->Export->"City of Heroes (Feet) (.geo)"  (or "City of Heroes (Meters) (.geo)" if your meshes have been scaled in meters).
3. Browse to the file you want to create and click "Export GEO".

## Notes

Models are exported with the name of the mesh they come from, so having the meshes named correctly is recommended.

# Tools

These command line tools allow inspection and modification of .geo files.

## geo.py
Contains the Geo class, which represents the contents of .geo files. Can be run to test the reading and writing functionality.

geo.py <infile.geo> [<outfile.geo>]

If only an input .geo file is specified, it will read the input and dump the contents of the .geo to the console.

If an output .geo file is specified, it will read the input .geo file, and write the contents to the output as a new .geo file.

## stl_dump.py
Dumps the meshes of a .geo file to .stl files. Used for testing and validation, as .stl isn't useful for games.

stl_dump.py <file.geo>

Dumps all the meshes contained in <file.geo> to <geo_name>/<model_name.stl>. <geo_name> and <model_name> are read from the .geo.

## geo_edit.py
A command line tool for modifying a .geo file

geo_edit.py <infile.geo> <outfile.geo> <operation> [<operation options> ...]

Operation                   | Description
--------------------------- | ---------------------------
  del_model <reg_ex>  | Deletes all models whose name contains the regular expression <reg_ex>.
  geo_name <name>     | Change the .geo's name to <name>.
  swap_left_right <reg_ex> | Swap left and right bones for all models matching <reg_ex>.
  rename_model <old> <new> | Rename a model from <old> to <new>.
  rename_texture <old> <new> | Rename a texture from <old> to <new>.
  rescale_all <scale> | Rescale all vertices in all models by multiplying them all by <scale> .
  set_model_scale <model> <x> <y> <z> | Set the scale properties of the given model (not the same as rescaling).
Multiple operations can be specified and performed in the same run.

Unless noted otherwise, model names and regular expressions are case sensitive.

## geo_list.py

A command line tool for list the model name inside of 1 or more .geo files.

geo_list.py [<output_options>] <file.geo> [<file.geo> ...]

The output format is:
<geo_name> : <model_name>

<output_options> adds additional items that can be outputted:
 -t Prints the triangle count of the model. Added output format:  ": <tri_count>"
 -s Prints the scale of the model. Added output format:  ": <sacle_x>, <sacle_y>, <sacle_z>"

## texture.py
Contains the Texture class, which represents .texture files. Can be run to test the reading and writing functionality.

Note: Requires Wand to be installed: http://wand-py.org/

texture.py <infile.texture> [<outfile.texture>]

If only an input .texture is specified, it will read the input file and dump the contents to the console.

If an output .texture is specified, it will read the input.texture file, and write the contents to the output .texture file.

## texture_extract.py
A command line tool for extracting an image from a .texture file.

Note: Requires Wand to be installed: http://wand-py.org/

texture_extract.py <infile.texture> [<outfile>]

Reads the file <infile.texture> and writes the contained image to an output file.

If <outfile> is specified it will write to this file. If no <outfile> is specified it will use the file name contained inside the .texture file, recreating the directory structure.

## dds2tex.py
A command line tool for converting a .dds file into a .texture .

Note: Requires Wand to be installed: http://wand-py.org/

texture_extract.py <infile.dds> [<outfile.texture> [<texture_filename>]]

<infile.dds> is the input file.

<outfile.texture> is the output file. If not specified it will use the same file name as the input except with a .texture extension. If <outfile.texture> is a directory it will use <texture_filename> with a .texture extension as the file name and directory, but placed under the directory <outfile.texture> .

<texture_filename> the filename to store inside the .texture file. If this not specified, it defaults to <infile.dds> . If <infile.dds> contains "texture_library" it will discard everything before "texture_library" use the remainder.


## Known Issues
 - Not all structures are handled (reflection quads)
 - Not all structures are regenerated when writing a .geo file. (Reductions)
 - Blender import of .geo files is currently a stub.