_ObjExporter
Date: 2019-10-22

org.jmol.export

## Class _ObjExporter

- java.lang.Object
- - org.jmol.export.___Exporter
  - - org.jmol.export.__CartesianExporter
    - - org.jmol.export._ObjExporter

-     public class _ObjExporter
      extends __CartesianExporter

  Class to export Wavefront OBJ files. The format is described at
  http://en.wikipedia.org/wiki/Wavefront_.obj_file
  and
  http://www.martinreddy.net/gfx/3d/OBJ.spec
  At least two files are produced: the object in the .obj file and the materials in the .mtl file. An additional image file is produced for each surface. All should be kept in the same directory.
  The exporter has been tested for ball and stick models, but not for:
  - outputFace (not used)
  - outputCone
  - outputTextPixel
  - outputTriangle
  - outputSurface (only some possibilities tested)
  Adapted for JavaScript by Bob Hanson 2/2014 using javajs.util.OC OutputChannel instead of File. This is way more flexible.
  Author:
    ken@kenevans.net

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private int` | `circleNum` Number for the next mesh of this type.
    `private int` | `coneNum` Number for the next mesh of this type.
    `private int` | `currentNormalOrigin` Wavefront OBJ refers to vertices and normals and textures by their location in the file.
    `private int` | `currentTextureOrigin` Wavefront OBJ refers to vertices and normals and textures by their location in the file.
    `private int` | `currentVertexOrigin` Wavefront OBJ refers to vertices and normals and textures by their location in the file.
    `private int` | `cylinderNum` Number for the next mesh of this type.
    `private static boolean` | `debug` Flag to cause debugging output to stdout.
    `private int` | `ellipseNum` Number for the next mesh of this type.
    `private int` | `ellipsoidNum` Number for the next mesh of this type.
    `private javajs.util.OC` | `mtlout` BufferedWriter for the .mtl file.
    `private int` | `nMtlBytes` Bytes written to the .mtl file.
    `private boolean` | `normalizeUV` Whether to normalize UV texture coordinates.
    `(package private) java.lang.String` | `objFileRootName` Path of the OBJ file without the extension.
    `private javajs.util.P3` | `ptTemp`
    `private int` | `sphereNum` Number for the next mesh of this type.
    `private int` | `surfaceNum` Number for the next mesh of this type.
    `private boolean` | `surfacesOnly` Flag to cause only surfaces to be output.
    `(package private) javajs.util.Lst<java.lang.String>` | `textureFiles` List of texture files created.
    `(package private) java.util.Set<java.lang.Short>` | `textures` HashSet for textures.
    `private int` | `triangleNum` Number for the next mesh of this type.

    - ### Fields inherited from class org.jmol.export.__CartesianExporter

      `canCapCylinders, noColor, sphereMatrix, viewpoint`

    - ### Fields inherited from class org.jmol.export.___Exporter

      `apertureAngle, backgroundColix, cameraDistance, cameraPosition, center, commandLineOptions, commentChar, degreesPerRadian, depthZ, export3D, exportScale, exportType, fileName, fixedRotationCenter, gdata, lightSource, lineWidthMad, out, privateKey, referenceCenter, scalePixelsPerAngstrom, screenHeight, screenWidth, slabZ, solidOnly, tempP1, tempP2, tempP3, tempV1, tempV2, tm, vwr`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `_ObjExporter()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `private void` | `addMesh(java.lang.String name, MeshSurface data, javajs.util.M4 matrix, javajs.util.M4 matrix1, short colix, int[] dim, javajs.util.BS bsValid)` Adds a new mesh using the given data (faces, vertices, and normals) and colix after transforming it via the given affine transform matrix.
    `private void` | `addTexture(short colix, java.lang.String name)` Adds a texture to the .mtl file if it is a new texture.
    `private javajs.util.OC` | `createTextureFile(java.lang.String name, MeshSurface data, int[] dim)` Writes a texture file with the colors in the colixes array in a way that it can be mapped by the texture coordinates vt.
    `protected void` | `debugPrint(java.lang.String string)` Debug print utility.
    `protected void` | `drawSurface(MeshSurface meshSurface, short colix)`
    `protected java.lang.String` | `finalizeOutput()`
    `private java.lang.String` | `getTextureName(short colix)` Returns the name to be used for the texture associated with the given colix.
    `(package private) boolean` | `initializeOutput(Viewer vwr, double privateKey, GData gdata, java.util.Map<java.lang.String,java.lang.Object> params)`
    `protected void` | `output(javajs.util.T3 pt)`
    `protected void` | `outputCircle(javajs.util.P3 pt1, javajs.util.P3 pt2, float radius, short colix, boolean doFill)`
    `private void` | `outputCircle1(javajs.util.P3 ptCenter, javajs.util.P3 ptPerp, short colix, float radius)` Local implementation of outputCircle.
    `protected void` | `outputCone(javajs.util.P3 ptBase, javajs.util.P3 ptTip, float radius, short colix)`
    `private void` | `outputCone1(javajs.util.P3 ptBase, javajs.util.P3 ptTip, float radius, short colix)` Local implementation of outputCone.
    `protected boolean` | `outputCylinder(javajs.util.P3 ptCenter, javajs.util.P3 pt1, javajs.util.P3 pt2, short colix, byte endcaps, float radius, javajs.util.P3 ptX, javajs.util.P3 ptY, boolean checkRadius)`
    `private void` | `outputCylinder1(javajs.util.P3 ptCenter, javajs.util.P3 pt1, javajs.util.P3 pt2, short colix, byte endcaps, float radius, javajs.util.P3 ptX, javajs.util.P3 ptY)` Local implementation of outputCylinder.
    `private boolean` | `outputEllipse1(javajs.util.P3 ptCenter, javajs.util.P3 ptZ, javajs.util.P3 ptX, javajs.util.P3 ptY, short colix)` Local implementation of outputEllipse.
    `protected void` | `outputEllipsoid(javajs.util.P3 center, javajs.util.P3[] points, short colix)`
    `private void` | `outputEllipsoid1(javajs.util.T3 center, float rx, float ry, float rz, javajs.util.A4 a, short colix)` Local implementation of outputEllipsoid.
    `protected void` | `outputFace(int[] face, int[] map, int faceVertexMax)`
    `private void` | `outputFace1(int[] face, int[] map, int[] map2)` Local implementation of outputFace used for no texture coordinates.
    `private void` | `outputFace2(int[] face, int vt, int[] map, int[] map2)` Local implementation of outputFace used with texture coordinates.
    `protected void` | `outputHeader()`
    `private void` | `outputList(javajs.util.T3[] pts, int nPts, javajs.util.M4 m, java.lang.String prefix, javajs.util.BS bsValid)` create the v or vn list
    `private void` | `outputMtl(java.lang.String data)` Write to the .mtl file and keep track of the bytes written.
    `protected void` | `outputSphere(javajs.util.P3 center, float radius, short colix, boolean checkRadius)`
    `protected void` | `outputTextPixel(javajs.util.P3 pt, int argb)`
    `protected void` | `outputTriangle(javajs.util.T3 pt1, javajs.util.T3 pt2, javajs.util.T3 pt3, short colix)`
    `private void` | `outputTriangle1(javajs.util.T3 pt1, javajs.util.T3 pt2, javajs.util.T3 pt3, short colix)` Local implementation of outputCylinder.

    - ### Methods inherited from class org.jmol.export.__CartesianExporter

      `drawAtom, drawCircle, drawCylinder, drawEllipse, drawPixel, drawTextPixel, fillConeScreen, fillCylinderScreen, fillCylinderScreenMad, fillEllipsoid, fillSphere, fillTriangle, getCameraPosition, getCoordinateMap, getModelCenter, getNormalMap, outputIndices, outputSolidPlate, plotImage, plotText, setSphereMatrix`

    - ### Methods inherited from class org.jmol.export.___Exporter

      `drawFilledCircle, finalizeOutput2, fixScreenZ, getByteCount, getColorList, getConeMesh, getExportDate, getJmolPerspective, getRotationMatrix, getRotationMatrix, getTriad, getTriadC, initOutput, opacityFractionalFromArgb, opacityFractionalFromColix, output, outputComment, outputFooter, outputJmolPerspective, outputSurface, outputVertex, outputVertices, rgbFractionalFromArgb, rgbFractionalFromColix, round, round, setTempVertex, translucencyFractionalFromColix`

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

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

- - ### Field Detail

    - #### debug

          private static final boolean debug

      Flag to cause debugging output to stdout.
      See Also:
        Constant Field Values

    - #### surfacesOnly

          private boolean surfacesOnly

      Flag to cause only surfaces to be output.

    - #### normalizeUV

          private boolean normalizeUV

      Whether to normalize UV texture coordinates. (Many applications expect them to be normalized.)

    - #### mtlout

          private javajs.util.OC mtlout

      BufferedWriter for the .mtl file.

    - #### objFileRootName

          java.lang.String objFileRootName

      Path of the OBJ file without the extension.

    - #### nMtlBytes

          private int nMtlBytes

      Bytes written to the .mtl file.

    - #### textures

          java.util.Set<java.lang.Short> textures

      HashSet for textures.

    - #### textureFiles

          javajs.util.Lst<java.lang.String> textureFiles

      List of texture files created.

    - #### sphereNum

          private int sphereNum

      Number for the next mesh of this type.

    - #### cylinderNum

          private int cylinderNum

      Number for the next mesh of this type.

    - #### ellipseNum

          private int ellipseNum

      Number for the next mesh of this type.

    - #### circleNum

          private int circleNum

      Number for the next mesh of this type.

    - #### ellipsoidNum

          private int ellipsoidNum

      Number for the next mesh of this type.

    - #### coneNum

          private int coneNum

      Number for the next mesh of this type.

    - #### triangleNum

          private int triangleNum

      Number for the next mesh of this type.

    - #### surfaceNum

          private int surfaceNum

      Number for the next mesh of this type.

    - #### currentVertexOrigin

          private int currentVertexOrigin

      Wavefront OBJ refers to vertices and normals and textures by their location in the file. This keeps track of where the latest vertex set starts.

    - #### currentNormalOrigin

          private int currentNormalOrigin

      Wavefront OBJ refers to vertices and normals and textures by their location in the file. This keeps track of where the latest normal set starts.

    - #### currentTextureOrigin

          private int currentTextureOrigin

      Wavefront OBJ refers to vertices and normals and textures by their location in the file. This keeps track of where the latest texture set starts.

    - #### ptTemp

          private final javajs.util.P3 ptTemp

  - ### Constructor Detail

    - #### _ObjExporter

          public _ObjExporter()

  - ### Method Detail

    - #### debugPrint

          protected void debugPrint(java.lang.String string)

      Debug print utility. Only prints if debug is true.
      Parameters:
        `string` -

    - #### outputFace

          protected void outputFace(int[] face,
                                    int[] map,
                                    int faceVertexMax)

      Specified by:
        `outputFace` in class `__CartesianExporter`

    - #### outputCircle

          protected void outputCircle(javajs.util.P3 pt1,
                                      javajs.util.P3 pt2,
                                      float radius,
                                      short colix,
                                      boolean doFill)

      Specified by:
        `outputCircle` in class `__CartesianExporter`

    - #### outputCone

          protected void outputCone(javajs.util.P3 ptBase,
                                    javajs.util.P3 ptTip,
                                    float radius,
                                    short colix)

      Specified by:
        `outputCone` in class `__CartesianExporter`

    - #### outputCylinder

          protected boolean outputCylinder(javajs.util.P3 ptCenter,
                                           javajs.util.P3 pt1,
                                           javajs.util.P3 pt2,
                                           short colix,
                                           byte endcaps,
                                           float radius,
                                           javajs.util.P3 ptX,
                                           javajs.util.P3 ptY,
                                           boolean checkRadius)

      Specified by:
        `outputCylinder` in class `__CartesianExporter`

    - #### outputEllipsoid

          protected void outputEllipsoid(javajs.util.P3 center,
                                         javajs.util.P3[] points,
                                         short colix)

      Specified by:
        `outputEllipsoid` in class `__CartesianExporter`

    - #### outputSphere

          protected void outputSphere(javajs.util.P3 center,
                                      float radius,
                                      short colix,
                                      boolean checkRadius)

      Specified by:
        `outputSphere` in class `__CartesianExporter`

    - #### outputTextPixel

          protected void outputTextPixel(javajs.util.P3 pt,
                                         int argb)

      Specified by:
        `outputTextPixel` in class `__CartesianExporter`

    - #### outputTriangle

          protected void outputTriangle(javajs.util.T3 pt1,
                                        javajs.util.T3 pt2,
                                        javajs.util.T3 pt3,
                                        short colix)

      Specified by:
        `outputTriangle` in class `__CartesianExporter`

    - #### outputHeader

          protected void outputHeader()

      Specified by:
        `outputHeader` in class `___Exporter`

    - #### output

          protected void output(javajs.util.T3 pt)

      Specified by:
        `output` in class `___Exporter`

    - #### drawSurface

          protected void drawSurface(MeshSurface meshSurface,
                                     short colix)

      Overrides:
        `drawSurface` in class `___Exporter`

    - #### initializeOutput

          boolean initializeOutput(Viewer vwr,
                                   double privateKey,
                                   GData gdata,
                                   java.util.Map<java.lang.String,java.lang.Object> params)

      Overrides:
        `initializeOutput` in class `___Exporter`

    - #### finalizeOutput

          protected java.lang.String finalizeOutput()

      Overrides:
        `finalizeOutput` in class `___Exporter`

    - #### outputMtl

          private void outputMtl(java.lang.String data)

      Write to the .mtl file and keep track of the bytes written.
      Parameters:
        `data` -

    - #### getTextureName

          private java.lang.String getTextureName(short colix)

      Returns the name to be used for the texture associated with the given colix. Jmol reading of the file without additional resources requires a color name here in the form: kRRGGBB
      Parameters:
        `colix` - The value of colix.
      Returns:
        The name for the structure.

    - #### outputCircle1

          private void outputCircle1(javajs.util.P3 ptCenter,
                                     javajs.util.P3 ptPerp,
                                     short colix,
                                     float radius)

      Local implementation of outputCircle.
      Parameters:
        `ptCenter` -
        `ptPerp` -
        `colix` -
        `radius` -

    - #### outputCone1

          private void outputCone1(javajs.util.P3 ptBase,
                                   javajs.util.P3 ptTip,
                                   float radius,
                                   short colix)

      Local implementation of outputCone.
      Parameters:
        `ptBase` -
        `ptTip` -
        `radius` -
        `colix` -

    - #### outputEllipse1

          private boolean outputEllipse1(javajs.util.P3 ptCenter,
                                         javajs.util.P3 ptZ,
                                         javajs.util.P3 ptX,
                                         javajs.util.P3 ptY,
                                         short colix)

      Local implementation of outputEllipse.
      Parameters:
        `ptCenter` -
        `ptZ` -
        `ptX` -
        `ptY` -
        `colix` -
      Returns:
        Always returns true.

    - #### outputEllipsoid1

          private void outputEllipsoid1(javajs.util.T3 center,
                                        float rx,
                                        float ry,
                                        float rz,
                                        javajs.util.A4 a,
                                        short colix)

      Local implementation of outputEllipsoid.
      Parameters:
        `center` -
        `rx` -
        `ry` -
        `rz` -
        `a` -
        `colix` -

    - #### outputCylinder1

          private void outputCylinder1(javajs.util.P3 ptCenter,
                                       javajs.util.P3 pt1,
                                       javajs.util.P3 pt2,
                                       short colix,
                                       byte endcaps,
                                       float radius,
                                       javajs.util.P3 ptX,
                                       javajs.util.P3 ptY)

      Local implementation of outputCylinder.
      Parameters:
        `ptCenter` -
        `pt1` -
        `pt2` -
        `colix` -
        `endcaps` -
        `radius` -
        `ptX` -
        `ptY` -

    - #### outputTriangle1

          private void outputTriangle1(javajs.util.T3 pt1,
                                       javajs.util.T3 pt2,
                                       javajs.util.T3 pt3,
                                       short colix)

      Local implementation of outputCylinder.
      Parameters:
        `pt1` - Vertex 1.
        `pt2` - Vertex 2.
        `pt3` - Vertex 3.
        `colix` - The colix.

    - #### addTexture

          private void addTexture(short colix,
                                  java.lang.String name)

      Adds a texture to the .mtl file if it is a new texture. Some of the parameter choices are arbitrarily chosen. The .mtl file can be easily edited if it is desired to change things.
      Parameters:
        `colix` -
        `name` - TODO

    - #### addMesh

          private void addMesh(java.lang.String name,
                               MeshSurface data,
                               javajs.util.M4 matrix,
                               javajs.util.M4 matrix1,
                               short colix,
                               int[] dim,
                               javajs.util.BS bsValid)

      Adds a new mesh using the given data (faces, vertices, and normals) and colix after transforming it via the given affine transform matrix.
      Parameters:
        `name` - The name to be used for the mesh.
        `data` - Where the data are located.
        `matrix` - Transformation to transform the base mesh.
        `matrix1` - Transformation for normals
        `colix` - Colix associated with the mesh.
        `dim` - The width, height of the associated image for UV texture coordinates. If null no UV coordinates are used.
        `bsValid` - TODO

    - #### outputList

          private void outputList(javajs.util.T3[] pts,
                                  int nPts,
                                  javajs.util.M4 m,
                                  java.lang.String prefix,
                                  javajs.util.BS bsValid)

      create the v or vn list
      Parameters:
        `pts` -
        `nPts` -
        `m` -
        `prefix` -
        `bsValid` - TODO

    - #### outputFace1

          private void outputFace1(int[] face,
                                   int[] map,
                                   int[] map2)

      Local implementation of outputFace used for no texture coordinates.
      Parameters:
        `face` -
        `map` - Map of data vertex indexes to output indexes
        `map2` - Map of data normal indexes to output indexes

    - #### outputFace2

          private void outputFace2(int[] face,
                                   int vt,
                                   int[] map,
                                   int[] map2)

      Local implementation of outputFace used with texture coordinates.
      Parameters:
        `face` - Array of vertices for the face.
        `vt` - Number of the vt texture coordinate.
        `map` - Map of data vertex indexes to output indexes
        `map2` - Map of data normal indexes to output indexes

    - #### createTextureFile

          private javajs.util.OC createTextureFile(java.lang.String name,
                                                   MeshSurface data,
                                                   int[] dim)

      Writes a texture file with the colors in the colixes array in a way that it can be mapped by the texture coordinates vt.
      Parameters:
        `name` - The name of the file without the path or ext. This will be added to the root name of the OBJ file along with the image suffix. The value should be the name given to the surface.
        `data` -
        `dim` - A Point representing the width, height of the image.
      Returns:
        The File created or null on failure.