documented the features introduced in the previous commit

doc/doc_filter_mrc.md

@@ -1496,7 +1496,6 @@ on separate lines in the file (which is in ASCII format).
 Blank lines are used to separate voxels belonging to different objects.
 There are two different file formats supported.
 
-
 You can define links for many different objects in the image
 in a single file by using blank-lines between different objects.
 The following examples describe two *different* connected objects.
@@ -1511,23 +1510,25 @@ and should range from 1 to Nx, Ny, or Nz (which define the image size).
 
 Considering the following text file:
 ```
-(16.5 77 73)
+(16 77 73)
 (134 75 73)
 
-(141.083 83.0833 62)
-(123.833 133.333 64)
+(141 83 62)
+(123 133 64) -1
 ```
 *(Note: You* ***must include spaces*** between each coordinate,
 even if commas are also present.)*
 
 This example describes two *different* connected objects
 (separated by a blank line).
 For each of these objects, all of the voxels connected to the
-first voxel (for example, near position 16.5, 77, 73)
+first voxel (for example, near position 16, 77, 73)
 will be joined with all of the voxels connected to the second voxel
 (near position 134, 75, 73).
 The voxels in the last two lines of the file
-will be connected together as well.
+will be connected together as well.  The "-1" indicates that the user wants
+to ensure that these last two surface fragments to point in opposite directions.
+
 
 *(Note: When using this format, coordinates are assumed to begin at 1,
        and are rounded down to the next lowest integer.
@@ -1580,6 +1581,79 @@ will be joined with all of the voxels connected to the second voxel
 *(Note: When using this format, voxel positions begin at 0, not 1.)*
 
 
+### Manual specification of fragment orientation
+
+#### Background
+
+If you are segmenting a membrane surface (or a curve), an ambiguity arises.
+Usually only a fraction of the surface or curve you are trying to
+detect is visible.  The remaining portion of the surface must be
+generated by some form of interpolation and/or reconstruction.
+Programs like "PoissonRecon" need to know the (signed) surface normal
+direction of each *visible* point on the surface.  Algorithms which
+detect the membrane surfaces can also detect this direction of the
+surface normal at each point.  But, in the case of a closed surface, it's
+often difficult for these algorithms to tell whether the direction
+detected at each voxel near the surface is pointing outward or inward.
+*(In other words, there is an ambiguity in the sign of the surface
+normal direction.)*  On the other hand, it is likely that
+two *nearby* surface fragments are probably pointing in similar directions.
+This means *filter_mrc* can usually assign directions to each fragment
+of the surface that are at least *consistent* with the other nearby fragments,
+even if it cannot tell which direction is inside or outside.
+*(It turns out that this is good enough for programs like "PoissonRecon".)*
+
+#### Explanation of the problem
+
+Unfortunately, if the user whats to join two *disconnected* surface (or curve)
+fragments together (using the "-must-link" argument),
+then there is no guarantee that these surface fragments
+are nearby or pointing in similar directions.
+By default, the *filter_mrc* program will attempt to figure out how the two
+fragments are oriented relative to each other.  However sometimes this fails.
+
+Suppose you are attempting to find a closed membrane surface
+(eg. using "PoissonRecon") that passes through multiple
+disconnected surface fragments, which you are linking together.
+Failure to determine the orientation of each surface fragment correctly will
+usually cause *PoissonRecon* to fail in a spectacular and visually obvious way.
+(This is rare.)  Hopefully most users will not encounter this error.
+Fortunately, if they do, they can *manually* specify the orientation of
+each successive fragment.
+
+#### Solution
+
+To do this, they can provide a fourth number
+(after the x,y,z coordinates), which is either 1 or -1.
+
+- A "1" means that the fragment is pointing in the same direction
+(or a similar direction) compared to its predecessor.  
+- A "-1" means they point in opposite directions.
+- If 0, or if left unspecified, the surface orientation will be
+determined automatically.
+
+*(WARNING: This is an experimental feature.
+  Please report bugs. -Andrew 2021-8-16.)*
+
+### Example 3: Specifying the relative orientation of surface fragments
+
+```
+(106 177 89)
+(149 181 93) 1
+723.3 381.6 178.5 -1
+(185 131 95)
+```
+
+The example above contains 4 surface fragments all linked together
+and merged into the same surface.  The "1" on the second line means that the
+second surface fragment points in a similar direction to its predecessor.
+The "-1" on the third line means that the third surface fragment points in
+the opposite direction of the second fragment.  *(As mentioned elsewhere,
+parenthesis are optional and determine the units of the coordinates.)*
+The orientation of the fourth surface fragment (at "(185 131 95)")
+will be determined automatically (since the "1" or "-1" was omitted).
+
+
 
 ### -select-cluster cluster-ID
 ### -normals-file PLY_FILE