= EQUALIZE =

||Category DART||Version 1.0||

== Description ==
'''EQUALIZE''' takes an input shape file and rearranges the vertices in an attempt to make the cells in the shape model more uniform. For bodies with funky shapes, points in the shape may cluster, which can cause artifacts during progressive levels of densify. Evening out the sizes of cells in the shape model can help avoid spikes and pinching in the model. '''EQUALIZE''' was added for 67P; however, it has proved useful for eliminating spikes (i.e., clustered shape models cells) that appear to be a consequence of extensive trimming in DART tests. '''EQUALIZE''' was not part of the blessed code used by OSIRIS-REx; it is being added to the DART Updates branch specifically to deal with side effects of trimming. Bob caveats that '''EQUALIZE''' is an experimental procedure. 

'''EQUALIZE''' goes along a line of the faces of the grid from one side to the other, computes the path length, and interpolates the points to more evenly space them along the path. After doing that to all the points, '''EQUALIZE''' does the same thing along the columns. The program will move every point on the edge, but not the corners that define the six faces of the cube. The latter options pertain to evening out the areas of the faces.

'''EQUALIZE''' does not affect maplets; it only affects the shape model. Run '''EQUALIZE''' only if needed, typically in between densify steps after you discover a spike. If you do use '''EQUALIZE''', record it in the notes file. 



== Input Files ==

 * [[INIT_LITHOS.TXT]]. 
 * SHAPEFILES/inputShape.TXT. '''EQUALIZE''' requires an input shape file, such as SHAPEFILES/SHAPE.TXT Replace "inputShape.TXT" with the name of the shape model you wish to '''EQUALIZE'''. 

== Output files ==
 * SHAPEFILES/outputShape.TXT. The equalized shape, which you should give a useful name e.g. SHAPEFILES/SHAPE3_0.25mGSDmaplets_equalized_YYYYMMDD.TXT.


== Using EQUALIZE ==

1. Invoke '''EQUALIZE''' and enter the desired input and output shapes. Replace "inputShape.TXT" and "outputShape.TXT" with the names of the files you are actually using.

{{{
EQUALIZE

Input original shapefile name
SHAPEFILES/inputShape.TXT

Input equalized shapefile name
SHAPEFILES/outputShape.TXT

}}}


2. Decide whether you wish to perform additional steps that attempt to further modify the shape model cells. These additional steps are presented as yes/no questions. Bob usually answers nnn, ynn, or yyn. In DART tests, Terik has used nnn.

 a. Interpolate corners. Choosing "y" averages the 3 nearest neighbors of each corner point to move that corner point to a new position.

 {{{
 INTERPOLATE CORNERS? (y/n)
 }}}


 b. Interpolate edges. Choosing "y" averages the two vectors straddling each edge point.

 {{{
 INTERPOLATE EDGES? (y/n)
 }}}


 c. Shrink face. Prior to asking this question, the program prints information to Terminal. The columns are: total area of face, minimum area of cell relative to average area of cell, maximum area of cell relative to average area of cell, average area of cell, standard deviation of cell area, and i1,j1 where minimum cell area is at i1,j1,f. Each row corresponds to a face. 

 {{{
         0.00715        0.00190        8.24864    0.27270E-07    0.20343E-07       134       221
         0.00544        0.00201        3.32848    0.20747E-07    0.71019E-08       389       374
         0.00686        0.46355        1.49439    0.26185E-07    0.59948E-08        19       511
         0.00507        0.40605        1.31625    0.19352E-07    0.32722E-08        20         9
         0.00772        0.00161        3.13246    0.29461E-07    0.16684E-07       252       182
         0.00469        0.51270        1.14856    0.17886E-07    0.15925E-08       434       490
  SHRINK FACE? (y/n) 
 
 }}}

 If you enter n, '''EQUALIZE''' ends. However, if you choose y, then the program asks you to

 {{{
 ENTER FACE
 }}}

 Enter the face that you wish to shrink (e.g., enter 1 if you wish to shrink the first face listed in the table. After doing that, the program loops back through the questions 

 {{{
 INTERPOLATE CORNERS? (y/n)
 INTERPOLATE EDGES? (y/n)
 SHRINK FACE? (y/n)
 }}}

 and continues to go through those until you choose n in response to SHRINK FACE? (y/n). 

3. Once you are satisfied, re-run densify.

== Usage tips ==

From Bob: "Basically I flail until the second column [printed before the SHRINK FACE (y/n)? option appears] is maybe half of the third so the ratio of the smallest to largest cell is about a half.  All of this flailing tends to smooth the model so the result is never final but a starting point for another densify run."

Keep track of what you do in the notes file! Your future self will thank you for keeping detailed notes.