axes

Tool tools/triage/axes.py (program, Triage). Find which axis is "up" in a 3D game's coordinates, its sign, and whether they are mirrored.

Run it with ./gameframe run axes ARGS or python3 tools/triage/axes.py. Source on GitHub.

Its own help

This is the help text in the tool itself, as ./gameframe tool axes prints it.

Find which axis is "up" in a 3D game's coordinates, its sign, and whether they are mirrored.

Usage: axes.py RECORDING GEOMETRY --pos X,Y,Z [--index I] [--scale S] [--left-turn T0:T1]
               [--cell SIZE] [--json]

  RECORDING    JSON Lines of an object that moves on the level's surface (a car, a walker), as
               tools/live/memrec.py record writes: {"t": seconds, NAME: value or [values], ...}
  GEOMETRY     the level's vertices, one point a line, "x y z" or "x,y,z" (# comments), in the
               same units as the positions once --scale is applied
  --pos        the three recorded values that hold the position, in the game's own order
  --index I    for array values (eight cars, say): which element (default 0)
  --scale S    multiply the recorded values by S first (1/65536 for 16.16 fixed point)
  --left-turn  a time span, in the recording's t, in which the object is known to turn left (the
               player steered left, the track bends left): gives the handedness
  --cell SIZE  the size of the grid used to find the surface under a point (default: 1/50 of
               the level's largest extent)

For each axis and each sign it takes that axis as "up", finds the vertices under every sample
in the other two axes (the grid cell and its neighbours), and measures how far above the
highest one the sample sits. On the right axis the object rides the surface: the height is
small and nearly the same in every sample. On a wrong axis the "surface under it" is any part
of the level, and the heights scatter. It prints the six candidates, best first, and the one
it picks. With --left-turn it then looks down the up axis and takes the sign of the turn: a
left turn is anticlockwise seen from above in right-handed coordinates (as OpenGL's), and
clockwise in left-handed ones (as Direct3D's). A port or viewer that draws the level mirrored
has the handedness wrong.

Output: the table and the verdict, or JSON with --json. Exit status 1 when no axis gives a
consistent height (fewer than half the samples above the surface, or a spread larger than a
tenth of the level).

It does not read the level's file format: export the vertices with the project's own reader.
It does not tell a yaw from a pitch, or find the order of the two flat axes beyond the
handedness. Standard library only.

Named by

Skills: re-observe.