Track Transformation

This article describes, how to transform a complete track including KMP, KCL, Model, Minimap and vrcorn. Transformation is any combination of scaling in 3 dimensions, rotating around 3 axis, translation (shift in to any direction).

Introduction

The main ideas of a track transformation is to scale a track (mostly down, sometimes up), because the track is too large or too small. Another reason is to change the height of the track over the ground, because the track is too low to the ground or too far away. And a third reason is to make a horizontal rotation to find a optimal start position or an optimal minimap placement.

For a complete track transformation you must at least transformate the positions (vertices) of the KMP (routes, positions, sizes and more), the KCL (collision file), the model (visible stuff) and the minimap. Additionally the vrcorn and other BRRES and KCL files can be transformed. The easiest way is to manipulate the vertex lists of the files and the KMP positions.

Since version 1.17, Wiimms SZS Tools allow scaling and shifting of whole tracks. The tools allow also scaling with different factors for the 3 dimensions and rotating around all 3 axes. Last not least they allow mirroring by using negative scale factors, but this may have different issues because of the changed culling.

After a transformation you must verify the track, especially the KMP needs user edits. In general, the KMP transformations works good, but it must be verified:

• The KMP section CKPT has only 2 dimensional points. If rotating vertically by --xrot or --zrot, the placement of the checkpoints are nearly always wrong. One way is to define a good y value as rotation base by using option --ypos.
• Item and enemy routes are normally good. Narrow turns may be problematic, if scaling down.
• Cameras and moving objects seems to be too fast if scaling down. Therefore speed factors in CAME, GOBJ and POTI must be changed.
• Objects are scaled by the scaling factors. If scaling with different factors for each dimension, objects are deformed too. Some objects, like itemboxes, can't be scaled.
• Verify the start position and the the respawn points.

Using the option --tform-kmp, the user can select KMP options and objects for the transformation.

Example

Let's start with a video example. In this example you see 6 transformed Nintendo tracks. Some tracks are only scaled and some tracks are deformed using different scaling factors for the 3 axis. You see, that KMP (routes, objects and more), KCL, course model, minimap and vrcorn transformed in the same way. The tracks are still playable.

The video shows only fully automated transformations without any user edits:

6 transformed Nintendo tracks

6 transformed tracks

Time	Slot	Track Name	Scaling	Options
0:00	1.1	Luigi Circuit	60%	--scale 0.6 --hrot 45
0:44	1.1	Luigi Circuit	100%,200%,50%	--scale 1,2,0.5 --hrot 45
1:46	1.2	Moo Moo Meadows	70%	--scale 0.7
2:31	2.3	DK Summit	70%, 150% vertical	--scale 0.7,1.5,0.7
3:46	2.4	Wario's Gold Mine	70%, 200% vertical	--scale 0.7,2,0.7
4:57	4.2	Moonview Highway	60%	--scale 0.6

All tracks have been scaled by:

wszst patch TRACK.szs --minimap MOREOPTIONS --tform-kmp -gobj

wszst

Tool to call.

patch

patch command of tool wszst.

TRACK.szs

The track file to patch.

Option --minimap

Adjust the minimap view area after transformation.

Option --tform-kmp -gobj

Select KMP sections and objects for a transformation. Here all section with exception of GOBJ (global objects) are transformed.

MOREOPTIONS

Track specific options, see table above.

The default is to patch only the main KCL, main KMP, course_model.brres and map_model.brres. The option --patch-file keywords allows to select, which kind of files is patched.

Using Wiimms SZS Tools

First, Wiimms SZS Tools are command line tools. So be sure to understand that concept before using the tools and asking for support.

Basic Transformation

The transformation is done for complete tracks files in the formats SZS, U8, WU8 or WBZ. Decompression and compression (SZS and WBZ), decoding and encoding (WU8 and WBZ) are done automatically and transparently. The command to use is »wszst patch«.

If you have a track file named CIRCUIT.szs and want to scale it down to 85%, use the command:

wszst patch --scale 0.85 CIRCUIT.szs

That's all. If you enter 3 different scaling values as comma separated list, you define different scaling factors for each axis. The following example scales the track horizontal to 90%, but vertically to 100% (unmodified):

3 axes of the coordinate system

wszst patch --scale 0.9,1,0.9 CIRCUIT.szs

You can for example also raise the track a little bit. Use the --shift or --translate options. Both options are similar: --shift is executed before any rotation and --translate behind. Again, enter 1 value for all 3 axis or 3 values for different parameters:

wszst patch --scale 0.85 --shift 0,1000,0 CIRCUIT.szs

If you want to rotate the track, add one or more of the options --xrot, --yrot or --zrot. Use the picture at the right to identify the axes. For a horizontal counter clockwise rotation of 45 degrees, add --yrot 45:

wszst patch --scale 0.85 --shift 0,1000,0 --yrot 45 CIRCUIT.szs

Execution Order

The transformation options are executed in the following logical order.

1. Scaling set by options --scale, --xss, --yss or --zss.
2. Shifting set by options --shift, --xss, --yss or --zss.
3. Rotation around the x-axis set by options --xrot or --rot.
4. Rotation around the y-axis set by options --yrot or --rot.
5. Rotation around the z-axis set by options --zrot or --rot.
6. Translation set by option --translate.

Shift and translate are very similar operations and the only difference is the execution before or after the rotation. The rotation itself is done as right-handed rotation with Euler angles and x-y-z convention. MDL0 files and the global objects of KMP/GOBJ don't know the shift operation, but to the other operations (scaling, rotation, translation) are done in exactly the same manner and in the same order.

Multiple Transformation Steps

The current transformation model is hard to manage, if you want to do several independent transformation steps, because you must mathematically combine them to the input model of the options. Some things are impossible to specify. For example scaling: If you want to scale only in one direction, it's only possible for the 3 axes, but it is impossible for other directions.

Option --next allows and separates up to 10 independent transformation steps. The option closes the current transformation step with all scaling, shifting, rotation and translation options and opens a new step with cleared options. On transformation each step is logical done one by one. In real, one final transformation matrix is calculated by multiplying the single step matrices and used for fast transformations.

Back to our scaling example above. If you want to scale your track horizontal by factor 2 into the direction between x- and z-axis (z-axis rotated 45 degrees around the y-axis), use the following options:

--yrot 45 --step --scale 2,1,1 --step --yrot -45

It rotates the axis, that should be scaled, 45 degree showing into x-direction, scales the x-axis and rotates back. The second --step is not really necessary, because scaling is done before rotation.

There are some problems using multiple transformation steps:

Some KMP sections (AREA, CAME and GOBJ) have scaling and rotation vectors. If using a simple transformation, these vectors are modified by multiplying the entered scale or adding the entered the rotation. But if using a complex transformation with multiple steps, these operation can't be done and scale and rotation vectors keep unchanged. A warning message is printed if this occurs. Position vectors are handled correct in any circumstance.

A similar problem exists for MDL0 transformations. For complex transformations it is impossible to modify the vectors of MDL bones. If the user decided so, the transformation mode is switched back to the default (VERTEX mode) for a full transformation support. A warning message is printed if this occurs.

Transformation Of Other Files

By default, only the main KCL and KMP, the model file (course_model.brres), the minimap file (map_modell.brres) and vrcorn.brres are transformed. But the patch command is able to transform also all other BRRES files and/or all other KCL files.

Therefore the option --patch-file=list is implemented. Just enter a list of file types you want to patch. The default is

--patch-file track,log

where »track« is a shortcut for »kcl,kmp,model,map« and »log« enables extended logging. If you want to disable VRCORN and to enable all other KCL files, use

--patch-file -vrcorn,other-kcl

The minus sign means: Use the previous setting (normally the default) and change some other file types (here VRCORN and all other KCL) of the transformation list.

Minimap

Another good option is --minimap to automatically adjust the minimap position:

wszst patch --scale 0.85 --shift 0,1000,0 --yrot 45 --minimap CIRCUIT.szs

More Details

All transformation options and more details are described here:

• Wiimms SZS Tools, Command PATCH, Transformation Options

Known Issues

• KMP object sunDSforces a freeze, if scaling the y-direction by factor 3 (other factors not tested). It is unsure, if the problem is the height or scaling of the sun, or its route or a combination of all.

Web-Links

Wiiki

• Rotation
• KCL (File Format)
• KMP (File Format)
• MDL0 (File Format)

Videos

• First demonstration video
• Second demonstration video (the one of the example above)

Discussion

• Forums wii-homebrew.com: Transformation ganzer Strecken (german)

Software

• Wiimms SZS Tools (Homepage & Download)

References

Custom Track Tutorials

Main Tutorials
Introduction – Textures – Scale – Modeling ⇒ Using Blender – BRRES: CTools
BRRES: BrawlBox – BRRES: RiiStudio – Minimap – Solidity – KCL: Wiimms Tools – KMP Editing
Object Editing – Cameras – Cannons – Post-effects – Videos

Battle Arenas
Battle Arenas – Enemy routes in battle arenas ⇒ Using Wiimm's Tools – Coins

Misc. Tutorials
Getting Files – BrawlBox Tricks – Animations – Shadows – Mipmaps
Custom Effects – Moving Terrain – Music – Ports – Paint Remakes – Tutorial Archive
Extended presence flags: Track Tutorial – LE-CODE Track FAQ

Testing and Reviewing
Testing a Track – Visual Review – Track Transformation – Fixing Errors

Software
3D Tools – BrawlBox – CTools Pack – KMP3D – KMP Cloud – KMP Modifier
Lorenzi's KMP Editor – MagicY – Material Tool – Post-Effect Editor – Wiimms SZS Tools – Wiimm's Tool Manager

Other
KMP Objects – Custom Objects – Model Database – Tutorial Archive