-------------------------------------------
var,funct: write Wavefront/Alias object surface (ASCII)
  set outsurf <surface>
  write_obj_surface
-------------------------------------------

Large Panel Only: [fn-]F3

The "OBJ" button on the "outsurf:" line on the
large fn-F3 panel writes out current surface as a
OBJ (Wavefront/Alias object format) ASCII file
whose name is current value of $outsurf (entry at
left) after auto-appending ".obj" if it isn't
already there.

The button checks overwrite but the equivalent
tclfunct, write_obj_surface, doesn't.

An *.obj file can be imported and displayed in
PhotoShop (tested on version 12.0, CS5).

  File -> Open -> exported *.obj file

The surface can them be manipulated in 3D within
PhotoShop.  Vertex colors are not imported in
Photoshop CS5, but are imported in 2018 and more
recent Photoshop.

The vertex coordinates are not transformed in any
way -- they are written in the native freesurfer
coordinate system (which may not display as a
lateral view of a hemisphere in an .obj file
viewer).  The units are millimeters.

Currently, only writes a triangle file.  The
format of the file is:

  --line 1: # comment line
   [begin vertices, v]
  --line 2: v <x> <y> <z> [<r> <g> <b>]
  --line 3: v <x> <y> <z> [<r> <g> <b>]
  ...
  ... [to vertex-count lines]
   [begin optional normals, vn]
  --line n+1: [vn <x> <y> <z>]
  --line n+2: [vn <x> <y> <z>]
  ...
  ... [to vertex-count lines]
   [begin faces, f]
  --line m+1: f <n1> <n2> <n3>   => 1st face vtx nums
  --line m+2: f <n1> <n2> <n3>   => 2nd face vtx nums
  ...
  ... [to face-count lines]

If normals are included, the vtx numbers in
the face lines will look like this:

   [begin faces, f]
  --line m+1: f <n1>//<n1> <n2>//<n2> <n3>//<n3>
  --line m+2: f <n1>//<n1> <n2>//<n2> <n3>//<n3>
  ...
  ... [to face-count lines]

N.B.: vtx numbers on faces lines are always
one-based! (not zero-based as in native
freesurfer formats).

Colored surfaces, optional include vertex normals

If this button is middle-clicked instead of
default left-clicked, the vertex colors of the 3
corners of each face are averaged and appended to
each face line (RGB in 0-1 units).

If this button is shift-middle-clicked instead of
default left-clicked, the x,y,z coordinates of
vertex normals are also included in the file.

Currently, any displayed transparent labels are
ignored when saving face/vertex colors.

Example output

An example .obj file with vertex colors (but no
normals) looks like this (indented below, but
natively left justified):

  # created by sereno (subj=seamol,vtxs=147326,faces=...
  v -10.977 -137.216 -23.560 0.162 0.605 0.162
  v -11.088 -137.341 -23.928 0.147 0.638 0.147
  v -11.166 -137.467 -24.370 0.135 0.666 0.135
  ...
  ...

  v -35.129 116.356 -33.792 0.089 0.768 0.089
  v -34.610 116.343 -33.769 0.066 0.818 0.066
  f 1 2 6
  f 7 6 2
  ...
  ...
  f 147326 144180 143327
  f 143327 144180 143753

