A quick reference guide to the user interface

File menu

Load surfaces launches a file selection dialog in which we select the two .ply|.wrl files by clicking on the first and ctrl-clicking on the second. Alternatively, we select a single .ply|.wrl file and let wxRegSurf look for a canonical .ply|.wrl in the same directory. Any filename containing the string canonical is treated as a "low resolution" (LR, red) surface that needs registering to the "high resolution" (HR, green) surface. If neither or both filenames contain this string, then the HR and LR surfaces are decided on a vertex count. wxRegSurf will quietly load any corresponding registration files it finds in the same directory. wxRegSurf can parse all .ply files and all .wrl files outputted by Stradwin. If you come across a valid .ply|.wrl file that wxRegSurf fails to load, please send it to us and we will update wxRegSurf's parsers.

Load surface data launches a file selection dialog in which we choose between the sw thickness file, sw density file and surface data file filters, then select the appropriate .bin file. wxRegSurf will quietly load any corresponding error file it finds in the same directory: these contain precision estimates at each vertex and are used to weight any data smoothing we might perform. The filenames for the cortical data must terminate in either _thickness.bin (Stradwin thickness), _density.bin (Stradwin density) or _dat.bin (general surface data). Stradwin thickness and density files contain one double precision binary floating point number per vertex. General surface data files start with an additional 256-byte binary header containing lower and upper range hints (two doubles) followed by an ASCII string specifying the units (null-padded to 240 bytes).

Save registration saves any registrations that have been modified since the last save. The .reg and .breg filenames are generated automatically from the surface names. The .reg file is human-readable text with a self-explanatory format. It contains the various global registration matrices and also the B-spline control point coordinates for the FFD alignments. The .breg files contain three single precision binary floating point numbers per vertex: these are the vertex coordinates (x, y and z, in that order) for the various nonparametric alignments.

Save LR-HR map writes a comma separated variable (.csv) file with two (no cortical data loaded) or four (LR and HR cortical data available) columns. The first is the index of each LR vertex, the second is the index of the matched HR vertex (or "unmatched"), the third is the LR data which may be "invalid", and the fourth is the HR data which may be "unmatched" or "invalid". The .csv file is named automatically, according to the two surface (two-column mode) or data (four-column mode) files that were loaded. It may be read into a spreadsheet or other software for further analysis.

Save LR data saves the current LR data and precision into .bin files. The filenames are generated automatically according to the source of the current LR data. The files themselves contain one double precision binary floating point number per vertex.

Save LR surface save a .ply file containing the currently displayed LR surface. The filename is generated automatically from the surface name and the current registration transformation.

Save screenshot saves a .png file of the current graphics window. The filename is generated automatically from the surface names.

Load and run batch file loads and parses a .run file. A batch file may include any number of blank or comment lines. The first non-comment line contains the full path to the working directory, where wxRegSurf will look for .ply|.wrl and .bin files. Each subsequent line contains a set of instructions for wxRegSurf to load files, process them and then save the results, as follows:


# LR surface  HR surface  LR data  HR data  reflect  smth LR  smth HR  range  fussy    n iter  reg type  save reg  save LR data  save map  review       rims
#                                                                             -1=auto          -=as->sm            -1 = no                 0 = no       0 = no
#                                                                                                                  0 = yes                 1-6 = angle  1 = yes
#                                                                                                                  >0 = smth               - = LR only  2 = to rims

The columns may be space or comma separated. See the wxRegSurf tutorials for example .run files.

Quit terminates wxRegSurf.

Help menu

Help displays these help pages.

About displays information about wxRegSurf's authorship.

Registration controls

Mouse changes the effect of mouse actions in the graphics window. Mouse->Viewpoint manipulates the viewpoint: left/middle mouse button to rotate, right mouse button to translate, scrollwheel to scale. Mouse->LR surface manipulates the LR surface, affecting the registration matrix for the currently selected registration type: left/middle mouse button to rotate, right mouse button to translate, scrollwheel to scale, single click to reflect. After manipulating the LR surface, remember to select Mouse->Viewpoint again.

Show HR surface toggles display of the high resolution (HR, green) surface.

Show LR surface toggles display of the low resolution (LR, red) surface.

White background changes the background of the graphics window from black to white. This is useful for producing screenshots that are going to be printed on paper.

Show matches displays the correspondences between LR and HR vertices. Standard matches are shown in white, fussy matches in magenta.

Surface shading selects the shading to apply to the surfaces. The various options should be self-explanatory. The colourmap scales for Gaussian curvature and the cortical data displays can be changed by positioning the mouse pointer on top of the scale bar and using the scrollwheel; the origin of the data displays can be shifted by simultaneously holding down the Alt key. A single click on the scale bar cycles through a selection of different colourmaps. The colourmap scale for the registration error is limited by the current search range. The three error distributions are displayed on the LR surface. You can query an individual data value by clicking and dragging over the surface with the Ctrl key held down.

Match rims controls how wxRegSurf treats vertices that lie on an open rim. When set to Yes, rim vertices are matched in the same way as other vertices. When set to No, wxRegSurf will not match an LR vertex to an HR vertex that lies on an open rim. This is a useful setting for femurs if the LR surface extends further down the femoral shaft than the HR surface. Note, however, that this will result in unmatched areas on the LR surface, so this setting is unsuitable for cohort analyses. When set to To rims, wxRegSurf will match LR rim vertices only to HR rim vertices, and favour rims in the registration process to ensure they align well.

Search range is the maximum distance that wxRegSurf will look for an HR vertex to match with each LR vertex. The units are x10mm, so the default value of 100 corresponds to 10mm.

Fussy % controls the proportion of fussy matches. Points subject to fussy matching are required to have similar surface normals and curvatures. It is the least well aligned LR vertices that are selected for fussy matching.

Auto sequence engages automatic sequencing of the search range and the proportion of fussy matches. This is often useful for vertebra cohort studies.

Aspect->Similarity transfers the current aspect ratio registration matrix to the similarity registration matrix, preserving the z scaling but adjusting the x and y scales to match. This is often useful for femur cohort studies.

Registration selects the type of registration transformation. The global options are rigid, similarity and aspect ratio. The local options are FFD (B-spline free form deformation), LAD (locally affine deformation) and SSM (statistical shape model, available only when a valid .ssm file is found in the same directory as the LR .ply|.wrl file).

Reset resets the parameters of the currently selected registration.

Iterations controls how many registration iterations to perform.

Start starts the registration iterations. This button then changes to Stop, allowing the iterations to be interrupted.

Smooth performs one smoothing cycle on any cortical data that is currently displayed. This process replaces each data value with a weighted average of immediately neighbouring values, with the weights set according to the precision estimates loaded at the same time as the data. If no precision estimates were loaded, uniform weighting is used.

Map sets the data at each LR vertex according to the data value at the matched HR vertex. Depending on the resolution of the two meshes, the HR data might need smoothing first, to ensure that the nearest neighbour mapping adequately captures all the HR data in the vicinity of each LR vertex. wxRegSurf will warn if there is a danger of undersampling.

Utilities controls

Show HR surface toggles display of the high resolution (HR, green) surface.

Show LR surface toggles display of the low resolution (LR, red) surface.

Show vertex displacements toggles display of the nonrigid LR vertex displacements. These are displayed as lines with their yellow ends at the undeformed vertex locations and their white ends at the deformed vertex locations.

SSM mode selects the SSM mode to visualize. This slider is activated only when a valid .ssm file is found in the same directory as the LR .ply|.wrl file.

SSM component adjusts the component of the current SSM mode. This slider is activated only when a valid .ssm file is found in the same directory as the LR .ply|.wrl file.

The Automatic SSM creator produces a statistical shape model for the current LR surface. It starts by identifying all the similarity+LAD registration files in the same directory as the current LR surface. It then performs principal component analysis on the vertex displacements, outputting the mean and up to fifty shape modes to a .ssm file. The filename is automatic and ends with the number of observations the SSM was constructed from (minimum three). The shape coefficients (i.e. the amount of each shape mode present in each observation) are written to a corresponding .csv file. If you rename the .ssm file to be the same as the LR surface file but with the suffix .ssm, then the next time you load the surface you will be able to visualise the shape modes in the Utilities tab. From here, you can also use the Save LR surface menu item to save a .ply file of the population mean or any of the shape modes.

The Automatic batch file writer produces batch files for surface registration and data mapping. It starts by identifying all the surface and data files in the same directory as the current LR surface. It then writes batch files for (a) registering the LR surface onto all the surfaces and (b) mapping all the data onto the LR surface. If the Defaults checkbox is checked, the batch files are populated with sensible default settings for femur cohort studies. Otherwise, the settings are read, where possible, from the controls on the Registration tab. Some manual editing of the batch files might be necessary for settings that cannot be read from the controls, for example the amount of LR and HR smoothing to apply when mapping data. For ease of editing, automatic batch files are comma separated and can therefore be loaded into a spreadsheet. Since the batch file names are fixed, you will need to rename them if you do not want them overwritten by subsequent runs of the automatic batch file writer.

Key presses

Pressing w toggles between shaded and wireframe renderings of the LR and HR surfaces.


Landmarks may be placed on the LR and HR surfaces by holding down the Ctrl key while clicking on the desired location. A pop-up dialog then prompts for the landmark's name. Ctrl-clicking on an existing landmark deletes it. LR and HR landmarks with identical names are preferentially matched and aligned during the registration process, as long as the distance between them does not exceed the current search range. Landmarks may be saved in surface files (Save LR surface) and reloaded later. Each landmark's name and location is stored as a comment in the .ply header as follows: comment LANDMARK "Landmark name" n, where n is the 0-based index of the vertex where the landmark is located.