RAS Coordinates in Scuba

This document is current as of 10/4/07.

Surface coordinates

The SurfaceCollection class is wrapper for an MRIS struct. It attempts to be as 'thin' as possible, that is, it doesn't attempt to replicate any functionality that doesn't already exist in libutils. It maintains a pointer to an MRIS struct and two transforms that concatenate the data->surface and world->surface transformations.

In SurfaceCollection, surface space is whatever coordinates are in the v->{x,y,z} fields for a surface. Data space is an intermediate space that allows a user-transform (i.e. a display transform) to be inserted between this space and the final world space. World space is equivalent to RAS space, since in Scuba, everything that is drawn on the screen is meant to be in RAS space.

You can think of the three spaces as:

• surface (TkRegRAS) -> data (un-user-transformed RAS) -> world (user-transformed RAS)

In the simple case where there is no user transform:

• surface (TkRegRAS) -> data (RAS) == world (RAS)

Note that the actualy transform objects in ScubaCollection are mDataToSurfaceTransform, mWorldToSurfaceTransform, and in the super class DataCollection, mDataToWorldTransform. The first two are the inverse of what you might expect.

In SurfaceCollection, the LoadSurface() function reads a surface with an MRISLoader, a class that eventually calls MRISread(). It then looks for a transform in mris->lta, and if found, populates its data->surface transform this way:

SurfaceCollection.cpp::LoadSurface():152

    // Get transform.
    if ( NULL != mMRIS->lta ) {

      // This is our RAS -> TkRegRAS transform.
      mDataToSurfaceTransform.SetMainTransform
      ( 1, 0, 0, -mMRIS->lta->xforms[0].src.c_r,
        0, 1, 0, -mMRIS->lta->xforms[0].src.c_a,
        0, 0, 1, -mMRIS->lta->xforms[0].src.c_s,
        0, 0, 0, 1 );
    }

The subsequent call to CalcWorldToSurfaceTransform() will concatenate any user transform, but initially there will be none, so the world->surface transform is identical to the data->surface.

So that's what you'll get if you just load up a surface in scuba. However, tkmedit does another transform automatically in which it 'associates' a surface with a volume. Since Scuba was designed to be totally flexible, it doesn't do this automatically. To associate a surface with a volume, show the Data panel, select the surface name in the Data Collection pull down menu, check the "Set RAS Transform from Volume" checkbox,, and select the proper volume in the Volume pull down menu right below it. This will cause the SetDataToSurfaceTransformFromVolume() function in SurfaceCollection to be called.

SetDataToSurfaceTransformFromVolume() has always been an uncertain part of Scuba since it was originally based on some instructions from Tosa, but stopped working at some point. Check the actual code for the old version. What it does now is:

SurfaceCollection.cpp::SetDataToSurfaceTransformFromVolume():631

  MATRIX* RASToTkRegRASMatrix = surfaceRASFromRAS_( mri );
  if ( NULL == RASToTkRegRASMatrix ) {
    throw runtime_error( "Couldn't get surfaceRASFromRAS_ from MRI" );
  }

  mDataToSurfaceTransform.SetMainTransform( RASToTkRegRASMatrix );
  MatrixFree( &RASToTkRegRASMatrix );

It replaces the data->surface transform with the surfaceRASFromRAS_() transform from the MRI the user selects in the pull down menu.

Excluding the new terminology of surface, data, and world space, the surface RAS transforms are actually very simple, and rely on the mrisurf.c code. Any future changes should be made in mrisurf.c, and SurfaceCollection should be kept as thin a wrapper as possible.