Polyhedra
Date: 2019-10-22

org.jmol.shapespecial

## Class Polyhedra

- java.lang.Object
- - org.jmol.shape.Shape
  - - org.jmol.shape.AtomShape
    - - org.jmol.shapespecial.Polyhedra

- All Implemented Interfaces:
    java.util.Comparator<java.lang.Object[]>

      public class Polyhedra
      extends AtomShape
      implements java.util.Comparator<java.lang.Object[]>

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private boolean` | `bondedOnly`
    `private javajs.util.BS` | `bsPolys`
    `private javajs.util.BS` | `bsVertexCount`
    `private javajs.util.BS` | `bsVertices`
    `private javajs.util.P3` | `center`
    `private javajs.util.BS` | `centers`
    `private static float` | `CONVEX_HULL_MAX`
    `private static float` | `DEFAULT_FACECENTEROFFSET`
    `private static float` | `DEFAULT_PLANAR_PARAM` a dot product comparison term
    `private float` | `distanceRef`
    `int` | `drawEdges`
    `static int` | `EDGES_ALL`
    `static int` | `EDGES_FRONT`
    `private static int` | `EDGES_NONE`
    `static int` | `EDGES_ONLY`
    `private int[][]` | `explicitFaces`
    `private static int` | `FACE_COUNT_MAX`
    `(package private) float` | `faceCenterOffset`
    `private boolean` | `haveBitSetVertices`
    `private boolean` | `iHaveCenterBitSet`
    `private java.util.Map<java.lang.String,java.lang.Object>` | `info`
    `private boolean` | `isAuto`
    `(package private) boolean` | `isCollapsed`
    `(package private) boolean` | `isFull`
    `private static float` | `MAX_DISTANCE_TO_PLANE`
    `private static int` | `MAX_OTHER`
    `private static int` | `MAX_VERTICES`
    `private static int` | `MODE_BITSET`
    `private static int` | `MODE_BONDING`
    `private static int` | `MODE_INFO`
    `private static int` | `MODE_POINTS`
    `private static int` | `MODE_RADIUS`
    `private static int` | `MODE_UNITCELL`
    `private int` | `modelIndex`
    `private javajs.util.V3[]` | `normalsT`
    `private int` | `nPoints`
    `private int` | `nVertices`
    `private javajs.util.P3[]` | `otherAtoms`
    `private float` | `planarParam`
    `private int[][]` | `planesT`
    `private float` | `pointScale`
    `int` | `polyhedronCount`
    `Polyhedron[]` | `polyhedrons`
    `private float` | `radius`
    `private float` | `radiusMin`
    `private static javajs.util.P3` | `randomPoint`
    `private java.lang.String` | `thisID`
    `private boolean` | `useUnitCell`
    `private javajs.util.V3` | `vAB`
    `private javajs.util.V3` | `vAC`
    `private javajs.util.V3` | `vBC`

    - ### Fields inherited from class org.jmol.shape.AtomShape

      `ac, atoms, bsSizeDefault, colixes, isActive, mad, mads, monomerCount, paletteIDs`

    - ### Fields inherited from class org.jmol.shape.Shape

      `bsColixSet, bsSizeSet, isBioShape, ms, myType, RADIUS_MAX, shapeID, translucentAllowed, translucentLevel, vf, vwr`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Polyhedra()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `private java.lang.Object` | `addEdge(javajs.util.Lst<int[]> faceEdgeList, java.util.Map<java.lang.String,java.lang.Object> htEdgeMap, java.lang.Integer normix, int[] p1, int i, javajs.util.P3[] points)` Check each edge to see that (a) it has not been used before (b) it does not have vertex points on both sides of it (c) if it runs opposite another edge, then both edge masks are set properly
    `private void` | `addFacet(int i, int j, int k, javajs.util.P3 ptRef, javajs.util.P3[] points, javajs.util.V3[] normals, int[][] faces, int planeCount, int nRef, boolean isWindingOK, javajs.util.V3 vTemp)` Add one of the three "facets" that compose the planes of a "collapsed" polyhedron.
    `private void` | `addPolyhedron(Polyhedron p)`
    `private javajs.util.BS` | `andBitSet(javajs.util.BS bs)`
    `private void` | `buildPolyhedra()`
    `private float` | `checkFacet(javajs.util.P3[] points, int nPoints, int[] t, int index, javajs.util.V3 norm, javajs.util.P4 pTemp, javajs.util.V3 vNorm, javajs.util.V3 vAC, java.util.Map<java.lang.Integer,java.lang.Object[]> htNormMap, java.util.Map<java.lang.String,java.lang.Object> htEdgeMap, float planarParam, javajs.util.BS bsTemp, java.lang.Object[] edgeTest)` Clean out overlapping triangles based on normals and cross products.
    `private boolean` | `checkID(java.lang.String thisID)`
    `int` | `compare(java.lang.Object[] a, java.lang.Object[] b)`
    `private Polyhedron` | `constructBitSetPolyhedron(Atom atom)`
    `private Polyhedron` | `constructBondsPolyhedron(Atom atom, int otherAtomCount)`
    `private Polyhedron` | `constructRadiusPolyhedron(Atom atom, AtomIndexIterator iter)`
    `private Polyhedron` | `constructUnitCellPolygon(Atom atom, boolean useBondAlgorithm)`
    `private void` | `deletePolyhedra()`
    `private Polyhedron` | `findPoly(java.lang.String id, int iatom, boolean allowCollapsed)`
    `private javajs.util.BS` | `findPolyBS(javajs.util.BS bsCenters)`
    `private int[]` | `fixExplicitFaceWinding(int[] face, int ipt, javajs.util.P3[] points, javajs.util.V3[] normals)` Check to see that the winding of the explicit face is correct.
    `private javajs.util.BS` | `getAtomsWithin(Polyhedron p, float offset)`
    `private int[][]` | `getFaces(int[][] triangles, int triangleCount, java.util.Map<java.lang.Integer,java.lang.Object[]> htNormMap)` Face: a CCW loop of edges all (within tolerance) in the same plane.
    `private int[][]` | `getFaceTriangles(int n, java.util.Map<java.lang.Integer,java.lang.Object[]> htNormMap, int triangleCount)`
    `int` | `getIndexFromName(java.lang.String id)`
    `java.lang.Object` | `getProperty(java.lang.String property, int i)`
    `boolean` | `getPropertyData(java.lang.String property, java.lang.Object[] data)`
    `java.lang.Object` | `getShapeDetail()`
    `java.lang.String` | `getShapeState()`
    `private boolean` | `isMatch(java.lang.String id)`
    `private boolean` | `isPlanar(javajs.util.P3 pt1, javajs.util.P3 pt2, javajs.util.P3 pt3, javajs.util.P3 ptX)`
    `private void` | `offsetPolyhedra(javajs.util.P3 value)`
    `private void` | `pointsPolyhedra(javajs.util.BS bs, float pointScale)`
    `private void` | `scalePolyhedra(float scale)`
    `private void` | `setDefinedFaces(javajs.util.P3[] points, int[][] faces)`
    `private int` | `setGap(javajs.util.P3 atom, int otherAtomCount)`
    `void` | `setModelVisibilityFlags(javajs.util.BS bsModels)`
    `private void` | `setPointsFromBitset()`
    `void` | `setProperty(java.lang.String propertyName, java.lang.Object value, javajs.util.BS bs)`
    `private void` | `setVisible(boolean visible)`
    `private boolean` | `testDiff(javajs.util.P3 a1, javajs.util.P3 b1, javajs.util.P3 a2, javajs.util.P3 b2)`
    `private Polyhedron` | `validatePolyhedron(javajs.util.P3 atomOrPt, int vertexCount)`

    - ### Methods inherited from class org.jmol.shape.AtomShape

      `checkColixLength, getInfoAsString, getSize, initModelSet, initShape, setAtomClickability, setColixAndPalette, setPropAS, setSize, setSize2, setSizeRD, setSizeRD2`

    - ### Methods inherited from class org.jmol.shape.Shape

      `appendCmd, checkBoundsMinMax, checkObjectClicked, checkObjectDragged, checkObjectHovered, coordinateInRange, encodeColor, findNearestAtomIndex, getColix, getColixA, getColixB, getColixI, getColorCommand, getColorCommandUnk, getFontCommand, getPropShape, getSizeG, getTranslucentLabel, initializeShape, replaceGroup, setModelSet, setPropS, setShapeSizeRD, wasClicked`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface java.util.Comparator

      `comparing, comparing, comparingDouble, comparingInt, comparingLong, equals, naturalOrder, nullsFirst, nullsLast, reversed, reverseOrder, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong`

- - ### Field Detail

    - #### DEFAULT_FACECENTEROFFSET

          private static final float DEFAULT_FACECENTEROFFSET

      See Also:
        Constant Field Values

    - #### EDGES_NONE

          private static final int EDGES_NONE

      See Also:
        Constant Field Values

    - #### EDGES_ALL

          public static final int EDGES_ALL

      See Also:
        Constant Field Values

    - #### EDGES_FRONT

          public static final int EDGES_FRONT

      See Also:
        Constant Field Values

    - #### EDGES_ONLY

          public static final int EDGES_ONLY

      See Also:
        Constant Field Values

    - #### MAX_VERTICES

          private static final int MAX_VERTICES

      See Also:
        Constant Field Values

    - #### FACE_COUNT_MAX

          private static final int FACE_COUNT_MAX

      See Also:
        Constant Field Values

    - #### MAX_OTHER

          private static final int MAX_OTHER

      See Also:
        Constant Field Values

    - #### otherAtoms

          private javajs.util.P3[] otherAtoms

    - #### normalsT

          private javajs.util.V3[] normalsT

    - #### planesT

          private int[][] planesT

    - #### randomPoint

          private static final javajs.util.P3 randomPoint

    - #### MODE_BONDING

          private static final int MODE_BONDING

      See Also:
        Constant Field Values

    - #### MODE_POINTS

          private static final int MODE_POINTS

      See Also:
        Constant Field Values

    - #### MODE_RADIUS

          private static final int MODE_RADIUS

      See Also:
        Constant Field Values

    - #### MODE_BITSET

          private static final int MODE_BITSET

      See Also:
        Constant Field Values

    - #### MODE_UNITCELL

          private static final int MODE_UNITCELL

      See Also:
        Constant Field Values

    - #### MODE_INFO

          private static final int MODE_INFO

      See Also:
        Constant Field Values

    - #### DEFAULT_PLANAR_PARAM

          private static final float DEFAULT_PLANAR_PARAM

      a dot product comparison term
      See Also:
        Constant Field Values

    - #### CONVEX_HULL_MAX

          private static final float CONVEX_HULL_MAX

      See Also:
        Constant Field Values

    - #### polyhedronCount

          public int polyhedronCount

    - #### polyhedrons

          public Polyhedron[] polyhedrons

    - #### drawEdges

          public int drawEdges

    - #### radius

          private float radius

    - #### radiusMin

          private float radiusMin

    - #### pointScale

          private float pointScale

    - #### nVertices

          private int nVertices

    - #### faceCenterOffset

          float faceCenterOffset

    - #### isCollapsed

          boolean isCollapsed

    - #### isFull

          boolean isFull

    - #### iHaveCenterBitSet

          private boolean iHaveCenterBitSet

    - #### bondedOnly

          private boolean bondedOnly

    - #### haveBitSetVertices

          private boolean haveBitSetVertices

    - #### centers

          private javajs.util.BS centers

    - #### thisID

          private java.lang.String thisID

    - #### center

          private javajs.util.P3 center

    - #### bsVertices

          private javajs.util.BS bsVertices

    - #### bsVertexCount

          private javajs.util.BS bsVertexCount

    - #### useUnitCell

          private boolean useUnitCell

    - #### nPoints

          private int nPoints

    - #### planarParam

          private float planarParam

    - #### info

          private java.util.Map<java.lang.String,java.lang.Object> info

    - #### distanceRef

          private float distanceRef

    - #### modelIndex

          private int modelIndex

    - #### isAuto

          private boolean isAuto

    - #### explicitFaces

          private int[][] explicitFaces

    - #### bsPolys

          private javajs.util.BS bsPolys

    - #### vAB

          private final javajs.util.V3 vAB

    - #### vAC

          private final javajs.util.V3 vAC

    - #### vBC

          private final javajs.util.V3 vBC

    - #### MAX_DISTANCE_TO_PLANE

          private static float MAX_DISTANCE_TO_PLANE

  - ### Constructor Detail

    - #### Polyhedra

          public Polyhedra()

  - ### Method Detail

    - #### compare

          public int compare(java.lang.Object[] a,
                             java.lang.Object[] b)

      Specified by:
        `compare` in interface `java.util.Comparator<java.lang.Object[]>`

    - #### setProperty

          public void setProperty(java.lang.String propertyName,
                                  java.lang.Object value,
                                  javajs.util.BS bs)

      Specified by:
        `setProperty` in class `Shape`

    - #### setDefinedFaces

          private void setDefinedFaces(javajs.util.P3[] points,
                                       int[][] faces)

    - #### pointsPolyhedra

          private void pointsPolyhedra(javajs.util.BS bs,
                                       float pointScale)

    - #### scalePolyhedra

          private void scalePolyhedra(float scale)

    - #### offsetPolyhedra

          private void offsetPolyhedra(javajs.util.P3 value)

    - #### getIndexFromName

          public int getIndexFromName(java.lang.String id)

      Overrides:
        `getIndexFromName` in class `Shape`
      Returns:
        index

    - #### getProperty

          public java.lang.Object getProperty(java.lang.String property,
                                              int i)

      Overrides:
        `getProperty` in class `Shape`
      Returns:
        true if serviced

    - #### getPropertyData

          public boolean getPropertyData(java.lang.String property,
                                         java.lang.Object[] data)

      Overrides:
        `getPropertyData` in class `Shape`
      Returns:
        true if serviced

    - #### getAtomsWithin

          private javajs.util.BS getAtomsWithin(Polyhedron p,
                                                float offset)

    - #### checkID

          private boolean checkID(java.lang.String thisID)

    - #### findPoly

          private Polyhedron findPoly(java.lang.String id,
                                      int iatom,
                                      boolean allowCollapsed)

      Parameters:
        `id` - may be null
        `iatom` - may be < 0 to (along with id==null) to get matching polyhedron
        `allowCollapsed` -
      Returns:
        Polyhedron or null

    - #### findPolyBS

          private javajs.util.BS findPolyBS(javajs.util.BS bsCenters)

    - #### isMatch

          private boolean isMatch(java.lang.String id)

    - #### getShapeDetail

          public java.lang.Object getShapeDetail()

      Overrides:
        `getShapeDetail` in class `Shape`

    - #### andBitSet

          private javajs.util.BS andBitSet(javajs.util.BS bs)

    - #### deletePolyhedra

          private void deletePolyhedra()

    - #### setVisible

          private void setVisible(boolean visible)

    - #### buildPolyhedra

          private void buildPolyhedra()

    - #### setPointsFromBitset

          private void setPointsFromBitset()

    - #### addPolyhedron

          private void addPolyhedron(Polyhedron p)

    - #### constructBondsPolyhedron

          private Polyhedron constructBondsPolyhedron(Atom atom,
                                                      int otherAtomCount)

    - #### constructUnitCellPolygon

          private Polyhedron constructUnitCellPolygon(Atom atom,
                                                      boolean useBondAlgorithm)

    - #### constructBitSetPolyhedron

          private Polyhedron constructBitSetPolyhedron(Atom atom)

    - #### constructRadiusPolyhedron

          private Polyhedron constructRadiusPolyhedron(Atom atom,
                                                       AtomIndexIterator iter)

    - #### setGap

          private int setGap(javajs.util.P3 atom,
                             int otherAtomCount)

    - #### validatePolyhedron

          private Polyhedron validatePolyhedron(javajs.util.P3 atomOrPt,
                                                int vertexCount)

    - #### fixExplicitFaceWinding

          private int[] fixExplicitFaceWinding(int[] face,
                                               int ipt,
                                               javajs.util.P3[] points,
                                               javajs.util.V3[] normals)

      Check to see that the winding of the explicit face is correct. If not, correct it. Also set the normals.
      Parameters:
        `face` -
        `ipt` -
        `points` -
        `normals` -
      Returns:
        correctly wound face

    - #### getFaceTriangles

          private int[][] getFaceTriangles(int n,
                                           java.util.Map<java.lang.Integer,java.lang.Object[]> htNormMap,
                                           int triangleCount)

    - #### addFacet

          private void addFacet(int i,
                                int j,
                                int k,
                                javajs.util.P3 ptRef,
                                javajs.util.P3[] points,
                                javajs.util.V3[] normals,
                                int[][] faces,
                                int planeCount,
                                int nRef,
                                boolean isWindingOK,
                                javajs.util.V3 vTemp)

      Add one of the three "facets" that compose the planes of a "collapsed" polyhedron. A mask of -2 ensures that only the [1-2] edge is marked as an outer edge.
      Parameters:
        `i` -
        `j` -
        `k` -
        `ptRef` - slightly out from the center; based on centerOffset parameter
        `points` -
        `normals` -
        `faces` -
        `planeCount` -
        `nRef` -
        `isWindingOK` -
        `vTemp` -

    - #### checkFacet

          private float checkFacet(javajs.util.P3[] points,
                                   int nPoints,
                                   int[] t,
                                   int index,
                                   javajs.util.V3 norm,
                                   javajs.util.P4 pTemp,
                                   javajs.util.V3 vNorm,
                                   javajs.util.V3 vAC,
                                   java.util.Map<java.lang.Integer,java.lang.Object[]> htNormMap,
                                   java.util.Map<java.lang.String,java.lang.Object> htEdgeMap,
                                   float planarParam,
                                   javajs.util.BS bsTemp,
                                   java.lang.Object[] edgeTest)

      Clean out overlapping triangles based on normals and cross products. For now, we use normixes, which are approximations of normals. It is not 100% guaranteed that this will work.
      Parameters:
        `points` -
        `nPoints` -
        `t` -
        `index` -
        `norm` -
        `pTemp` -
        `vNorm` -
        `vAC` -
        `htNormMap` -
        `htEdgeMap` -
        `planarParam` -
        `bsTemp` -
        `edgeTest` -
      Returns:
        0 if no error or value indicating the error

    - #### addEdge

          private java.lang.Object addEdge(javajs.util.Lst<int[]> faceEdgeList,
                                           java.util.Map<java.lang.String,java.lang.Object> htEdgeMap,
                                           java.lang.Integer normix,
                                           int[] p1,
                                           int i,
                                           javajs.util.P3[] points)

      Check each edge to see that (a) it has not been used before (b) it does not have vertex points on both sides of it (c) if it runs opposite another edge, then both edge masks are set properly
      Parameters:
        `faceEdgeList` -
        `htEdgeMap` -
        `normix` -
        `p1` -
        `i` -
        `points` -
      Returns:
        true if this triangle is OK

    - #### testDiff

          private boolean testDiff(javajs.util.P3 a1,
                                   javajs.util.P3 b1,
                                   javajs.util.P3 a2,
                                   javajs.util.P3 b2)

    - #### isPlanar

          private boolean isPlanar(javajs.util.P3 pt1,
                                   javajs.util.P3 pt2,
                                   javajs.util.P3 pt3,
                                   javajs.util.P3 ptX)

    - #### getFaces

          private int[][] getFaces(int[][] triangles,
                                   int triangleCount,
                                   java.util.Map<java.lang.Integer,java.lang.Object[]> htNormMap)

      Face: a CCW loop of edges all (within tolerance) in the same plane. Objective is to find all triangles with *essentially* the same normal and to then group them into a face. But we have to be careful here; not everything is perfect. We can have be so slightly off in a 4- or 6-face, and we still want it to be called a face. We allow a normal dot product (i.e. cos(theta)) to be < 0.05. This empirically seems to work.
      Parameters:
        `triangles` -
        `triangleCount` -
        `htNormMap` -
      Returns:
        array of CCW connecting edges

    - #### setModelVisibilityFlags

          public void setModelVisibilityFlags(javajs.util.BS bsModels)

      Overrides:
        `setModelVisibilityFlags` in class `Shape`

    - #### getShapeState

          public java.lang.String getShapeState()

      Overrides:
        `getShapeState` in class `AtomShape`