Style Campaign SVG Generator [scVector]

Contents

* The Basics
* The config file
* The scene file
* Supported files
* The Controls
* The Modes
* Notes

The Basics

Please read the accompanying readme.html before proceeding.

scVector is a simple tool for generating SVG files from 3D rendered scenes. It is designed to be largely WYSIWYG though background colors are not exported in the final SVG output. This is a deliberate exception as typically you would wish to define background color in the HTML file containing the SVG content. The 3D preview is fully interactive to allow for composition of the final output.
scVector is a modification of a proprietary 3D engine originally designed to be a lightweight game development platform. It is, at its core, a software renderer with no external dependencies. Any limitations in its performance or functionality are inherited from this original design purpose. scVector was developed as an in house experiment at Style Campaign and any UI or stability issues may be reflected in this fact.

scVector is a Win32 executable. Supported platforms include Microsoft Windows XP and Windows 7, Windows 8 may also be supported but has not been tested. There are no immediate plans to support Mac OSX or Linux.

All output files will be written to the directory of the scene file. File paths may be relative or absolute when defined within the scene file. All SVG output files will be named with the format sceneXXXX.svg where 'scene' represents the name of the specified scene file and 'XXXX' represents an index starting at 0 in the order files are created within a given session, new sessions always start at 0 and previously generated files of the same name will be overwritten.

The config file

The config file has only three entries:

scene file name | screen width | screen height

All paths are relative to the executable. Even if the scene file is in an alternate directory the paths defined in the scene file will be relative to the executable, not the scene file. However, any paths in the 3D model files will be relative to the base model file, i.e the .obj file for Wavefront objects or the .ms3d file Milkshape objects. The output path will always reflect the path to the scene file.

Screen width and screen height can be set to any reasonable value though increasing screen size may negatively affect performance. The minimum value for screen width is 320, for screen height the minimum value is 240. There are no maximum values. The Screen resolution will be reflected in the SVG viewport size.

The scene file

The scene file describes the 3D scene and sets some basic properties that the engine requires to draw the 3D content.
The scene file may contain comments, any line starting with the # prefix will be ignored by the parser.
All properties defined in the scene file are prefixed by an identifying letter followed by one or more values. The values must be defined in the manner specified or errors will occur, there is no fault tolerance in the parser and any badly formatted entry will have undefined consequences.

All scene file definitions should contain space separated values, no commas, colons etc. and must be on a separate line.

The scene file must contain the following definitions:

a: ambient light color, three floating point values representing red, green and blue components of the ambient light in the following format:
a float float float

k: shadow color, three floating point values representing red, green and blue components of the shadow polygons in the following format:
k float float float

b: background color, three floating point values representing red, green and blue components of the background color (fill color) of the scene in the following format:
b float float float

l: light color, three floating point values representing red, green and blue components of the scene light in the following format:
l float float float

c: light position, three floating point values representing the x, y and z components of the scene light. The scene light is actually a three unit normalized vector pointing from the light position to the origin. The light position is defined in the following format:
l float float float

o: origin, three floating point values representing the x, y and z components of the virtual camera position defined in the following format:
o float float float

f: field of view, a single floating point value representing the virtual camera's field of view (view angle) defined in the following format:
f float

The scene may then contain the model file definitions.

The first line of the model file definition will always contain the following:
g mesh

Subsequently the definitions are as follows:

m: mesh definition, one string containing the name (and relative path) of the object to be loaded, and two floating point values. The first floating point value representing the scale at which the shape is to be loaded and the second value representing the shadow offset, which defines the height of the plane that the shadow is projected into relative to the shape.
The mesh file is defined in the following format:
m string float float

v: mesh location, three floating point values representing the x, y and z components of the objects position within the scene, in the following format:
v float float float

v: mesh rotation, three floating point values representing the x, y and z components of the objects rotation within the scene, in the following format:
v float float float

The model file definition should ideally appear as a group as follows:

g mesh
m string float float
v float float float
v float float float

Multiple model file definitions can be included, the order in which they are defined will be the order in which they are drawn within the screen and subsequently the order in which they are exported to the SVG file. At present the maximum number of models that can be loaded into a scene is sixteen, attempting to load more than sixteen shapes will result in undefined behavior.

Supported files

Texture files can be BMP files at any bit depth or JPEG files. A model file can contain up to 128 unique materials, each of which may contain a texture reference. However, only a total of 256 materials can be loaded into any given scene.
Internally all textures have uniform (width=height) power of two (2 to the n) dimensions (2,4 8,16,32,64....) with a maximum resolution of 4096. Ideally all shape textures should be supplied in this format. Textures with irregular dimensions will be scaled to the nearest power of two value, this may result in loss of texture detail/fidelity.

Wavefront Object files (.obj) commonly referred to as OBJ or WFO are the default object format. The Wavefront Object file specification is somewhat loosely defined. However, most common formats are supported. OBJ files can be supplied with or without an associated material file (.mtl). Objects without material files will be loaded with default material properties and a diffuse color value of 0x808080 (128,128,128 rgb). OBJ files may be supplied without vertex normals defined, normals will be calculated at load time, and without UV texture coordinates. Though best results will be achieved with fully defined object properties. OBJ formats that are not supported will result in undefined behavior.

Mikshape 3D files (.ms3d) are also supported with full implementation of rigged animated shapes.

All object files must have a maximum of four vertices per polygon, loading shapes with more that four vertices per polygon will result in undefined behavior.

The Controls

scVector has a comprehensive list of keyboard commands. A summary of these commands can be viewed at any time by hitting the F1 key. The following is a (slightly) more definitive explanation of these commands.

F1 : show the keyboard command list summary.

F12 : select next shape
Only one shape is 'active' at any given time. Using the commands to rotate, translate or change the rendering options will apply to the currently selected shape. Hitting the F12 key will toggle through all the shapes in the scene selecting each one in turn. The print out at the top of the screen will list the currently selected shape when the F12 key is pressed.

'.' : next render mode
There are currently ten render modes. A shape must be in modes 2-9 in order to be exported to the SVG file. All modes will give slightly different export results particularly when exporting textured shapes. Hitting the '.' will toggle through the available modes for the currently selected shape.

',' : previous render mode
As above, just in reverse.

'v' : write SVG output
Pressing the 'v' key will export the current scene to an SVG file. All SVG output files are named with the format sceneXXXX.svg where 'scene' represents the name of the specified scene file and 'XXXX' represents an index starting at 0. Repeatedly pressing the 'v' key will produce multiple SVG files. SVG files are written to the directory containing the scene file.

+ SHIFT : wireframe output
Holding the SHIFT key and pressing the 'v' key will export the scene with all active shapes rendered as solid wireframe shapes, The color of the wireframe is the same as the shadow color, this can easily be altered in the resulting SVG file as the stroke color is only defined once.

+ CAPSLOCK : no back face cull
Holding the CAPSLOCK key while pressing the 'v' key will turn off back face culling, all polygons in the shape will be rendered to the SVG output. This may be useful for animation purposes. The CAPSLOCK key can be used with the SHIFT key for wireframe output.

or TAB : back face only
Holding the TAB key while pressing the 'v' key will force only back facing polygons to be rendered to the SVG. This may prove useful when creating transparent shapes or in any instance where back face polygons need to be created in a separate group. The TAB key can be used in conjunction with the SHIFT key for wireframe output. Using the TAB key with the CAPSLOCK key will have no effect.

MOUSE : rotate camera
Click and drag the mouse to rotate the camera, only x,y rotations of the camera are supported. The camera may also be rotated using the 'w','a','s','d' keys and holding the SHIFT key.

MOUSE + SHIFT : rotate current shape (y axis)
Click and drag the mouse while holding the SHIFT key to rotate the current active shape in the y axis.

+ CAPSLOCK : rotate current shape (z axis)
Click and drag the mouse while holding the SHIFT and CAPSLOCK keys to rotate the current active shape in the z axis.

or TAB : rotate current shape (x axis)
Click and drag the mouse while holding the SHIFT and TAB keys to rotate the current active shape in the x axis.

'w' : push camera z axis
Pressing the 'w' key will move the camera forwards along the camera's z axis, translation of the camera is in the camera's local coordinate system, so no matter what the orientation of the camera pressing the 'w' key will move the camera in the direction the camera is facing.

's' : push camera -z axis
Pressing the 's' key will move the camera backwards along the camera's z axis, translation of the camera is in the camera's local coordinate system, so no matter what the orientation of the camera pressing the 's' key will move the camera in the opposite direction the camera is facing.

'd' : push camera x axis
Pressing the 'd' key will move the camera forwards along the camera's x axis, translation of the camera is in the camera's local coordinate system, so no matter what the orientation of the camera pressing the 's' key will move the camera to the right in relation to the direction the camera is facing.

'a' : push camera -x axis
Pressing the 'a' key will move the camera backwards along the camera's x axis, translation of the camera is in the camera's local coordinate system, so no matter what the orientation of the camera pressing the 'a' key will move the camera to the left in relation to the direction the camera is facing.

'y' : push camera y axis
Pressing the 'y' key will move the camera forwards along the camera's y axis, translation of the camera is in the camera's local coordinate system, so no matter what the orientation of the camera pressing the 'y' key will move the camera up in relation to the direction the camera is facing.

'Y' : push camera -y axis
Pressing the 'Y' key will move the camera backwards along the camera's y axis, translation of the camera is in the camera's local coordinate system, so no matter what the orientation of the camera pressing the 'Y' key will move the camera down in relation to the direction the camera is facing.

UP : push current shape z axis
Pressing the UP arrow key will move the current active object forwards along the z axis, translation of shapes is in the global coordinate system and never changes.

DOWN : push current shape -z axis
Pressing the DOWN arrow key will move the current active object backwards along the z axis.

LEFT : push current shape -x axis
Pressing the LEFT arrow key will move the current active object backwards along the x axis.

RIGHT : push current shape x axis
Pressing the RIGHT arrow key will move the current active object forwards along the x axis.

PGUP : push current shape y axis
Pressing the PGUP key will move the current active object forwards (up) along the y axis.

+ SHIFT: push current shape's shadow y axis
Pressing the PGUP and SHIFT keys will move the current active object's shadow forwards (up) along the y axis.

PGDN : push current shape -y axis
Pressing the PGDN key will move the current active object backwards (down) along the y axis.

+ SHIFT: push current shape's shadow y axis
Pressing the PGDN and SHIFT keys will move the current active object's shadow backwards (down) along the y axis.

'r' : reset current shape position, rotation
Pressing the 'r' key will reset the current shape. The shape will be set the it's original position and orientation as defined in the scene file.

+ CTRL : fine control Holding the CTRL key while performing any other action will reduce the amount of translation/rotation caused be the action providing finer control.

'h': toggle shape visibility
Hitting the 'h' key will toggle the visibility of he current active shape. This can be useful when working with multiple shapes. Hidden shapes are completely excluded from the export precess and will not be written to the SVG.

'f' : apply action to all shapes
Any action may be applied to all shapes simultaneously by holding the 'f' key while performing the action. The can prove useful when processing multiple shapes for animation purposes.

ms3d only:
The following apply to Milkshape 3D animated objects only.

'[' : decrease fps
Pressing the '[' key will incrementally reduce the frame rate of the current active animated shapes playback.

']' : increase fps
Pressing the ']' key will incrementally increase the frame rate of the current active animated shapes playback.

'{' : pause animation
Pressing the '{' key will set the current active shapes animation rate to 0.0 fps, effectively pausing the animation.

'}' : set fps default
Pressing the '}' key will set the current active shapes animation rate to 12.5 fps, the default playback speed for animated shapes.

The Modes

scVector has ten rendering modes:
1. Flat unlit/fullbright preview
2. Flat shaded center face
3. Flat shaded center face with pseudo phong specularity
4. Flat shaded average face
5. Flat shaded average face with pseudo phong specularity
6. Flat shaded center face with shadow
7. Flat shaded center face with pseudo phong specularity and shadow
8. Flat shaded average face with shadow
9. Flat shaded average face with pseudo phong specularity and shadow
10. Gouraud shaded preview with shadow

The following definitions apply:
'center face' - Polygon color determined using texel color at center face. Internally all material
colors are textures, even if no texture is specified in the model file.
'average face' - Polygon color determined using average texel color for entire face.
'pseudo phong specularity' - Specular reflection at highlights, though not at incidence angle as with true phong shading.

SVG's can only be exported when rendering mode is 2-9.

Notes

"undefined behavior" is programmer speak for "something is going to go terribly wrong" and can usually be interpreted as "it will crash".

Style Campaign, March 10, 2014