Package org.bzdev.p3d

Interface Model3D.ImageData

All Known Implementing Classes:
Model3D.Image, Model3D.ImageDataImpl
Enclosing class:
Model3D

public static interface Model3D.ImageData
Data used by a Model3D.Image instance to render an instance of Model3D. The image described by this interface will have a height and width given by the methods getHeight() and getWidth(). One can specify an origin (e.g., by calling (@link ImageData#setOrigin(double,double)} or related methods) to indicate where a 3-D model's point (0.0, 0.0, 0.0) (after rotations and translations) may appear. This origin is specified using the Java convention where increasing X values move right and increasing Y values move down. The model can also be scaled by calling {ImageData#setScaleFactor(double)}. The scaling will be done so that the model's point (0.0, 0.0, 0.0) will appear at the origin for all scale factors.

To provide different views of a model, the model's coordinate system can be transformed - the behavior specified above applies to the the transformed coordinate system. This transformation is specified by the methods setRotationOrigin(double,double,double), setRotationOrigin(double,double,double,boolean), setCoordRotation(double,double,double); setTranslation(double, double)

To make the model appear to be three dimensional, the brightness of the surface depends on the angle the surface makes with the direction of a light source. The light source can be positioned by calling setLightSource(double,double). To help distinguish parallel faces, the method setColorFactor(double) can be used. This will configure the image rendering so that more distant areas are dimmer. Z-order issues may impact rendering. The method setDelta(double) can be used to partition large triangles into a number of smaller one.

One can specify colors various features such as lines showing the triangles that make up model, the interior (or 'back') side of a triangles (which should never by visible), etc. The methods used for this purpose are setBacksideColor(Color), setEdgeColor(Color), setDefaultSegmentColor(Color), and setDefaultBacksideSegmentColor(Color).

Finally, while flexible, adjusting all the coordinate transformations can be tedious. For the common case, one would use the setCoordRotation(double,double,double) to orient the view of a model, and a Model3D method named setImageParameters to scale and translate a model to match the available space that an image has. These methods are Model3D.setImageParameters(Model3D.ImageData), Model3D.setImageParameters(Model3D.ImageData,double), Model3D.setImageParameters(Model3D.ImageData,double,double), Model3D.setImageParameters(Model3D.ImageData,double,double,double), Model3D.setImageParameters(Model3D.ImageData,double,double,double,double), and Model3D.setImageParameters(Model3D.ImageData,double,double,double,double,boolean).

  • Method Summary

    Modifier and Type
    Method
    Description
    Get the color for the the side of a triangle that should not be visible due to being on the inside of a closed manifold.
    double
    Get the color factor.
    Get the default backside color to use for line segments associated with triangles added for rendering.
    Get the color to use for line segments explicitly added or associated with triangles added for rendering.
    double
    Get the minimum triangle size for rendering.
    Get the color used to indicate the edges of a triangle
    float
    Get the height of an image.
    float
    Get the width of an image .
    int
    Get the height of an image as an integer.
    Get the corresponding ImageDataImpl.
    double
    Get the light-source parameter phi.
    double
    Get the light-source parameter theta.
    double
    Get the normal factor After a coordinate transformation, the normal factor is used to reduce the color factor towards 0.0 when a surface segment' is not aligned with the Z axis.
    double
    Get the Eulerian angle phi for a coordinate rotation.
    double
    Get the Eulerian angle psi for a coordinate rotation.
    double
    Get the X coordinate of the origin/target point for a coordinate rotation.
    double
    Get the Y coordinate of the origin/target point for a coordinate rotation.
    double
    Get the Z coordinate of the origin/target point for a coordinate rotation.
    double
    Set the scale factor.
    double
    Get the Eulerian angle theta for a coordinate rotation.
    int
    Get the width of an image as an integer.
    float
    Get the X coordinate of the origin.
    double
    Get the coordinate translation in the X direction that will be applied after other coordinate transformations are completed.
    float
    Get the Y coordinate of the origin Note that user space follows the standard Java convention in which increasing X values go 'right' on an image and increasing Y values do 'down'.
    double
    Get the coordinate translation in the Y direction that will be applied after other coordinate transformations are completed.
    boolean
    Determine if the transformed origin for (0,0,0) will be moved to the coordinate origin after the rotation is completed.
    void
    Reset to default values.
    void
    Set the color for the side of a triangle that should not be visible due to being on the inside of a closed manifold.
    void
    setColorFactor(double factor)
    Set the color factor.
    void
    setCoordRotation(double phi, double theta, double psi)
    Rotate the Model3D coordinates.
    void
    Set the default backside color to use for line segments associated with triangles added for rendering.
    void
    Set the color to use for line segments explicitly added or associated with triangles added for rendering.
    void
    setDelta(double delta)
    Set the minimum triangle size for rendering.
    void
    Set the color to use to use to draw the edges of triangles.
    void
    setLightSource(double phi, double theta)
    Sets the direction to a light source.
    void
    setNormalFactor(double factor)
    Set the normal factor.
    void
    Set the origin to a default value.
    void
    setOrigin(double offset)
    Set the origin given a double-precision offset.
    void
    setOrigin(double x, double y)
    Set the origin give double-precision coordinates The origin is the point on the image that will correspond to points in the model for which x = 0.0 and y = 0.0.
    void
    setOrigin(float offset)
    Set the origin given an offset.
    void
    setOrigin(float x, float y)
    Set the origin given floating-point coordinates.
    void
    setOrigin(int offset)
    Set the origin given an integer offset.
    void
    setOrigin(int x, int y)
    Set the origin given integer coordinates.
    void
    setOriginByFraction(double offset)
    Set the origin given a double-precision fractional offset.
    void
    setOriginByFraction(float offset)
    Set the origin given a single-precision fractional offset.
    void
    setRotationOrigin(double x, double y, double z)
    Move the rotation origin for a coordinate rotation.
    void
    setRotationOrigin(double x, double y, double z, boolean move)
    Move the rotation origin for a coordinate rotation with options.
    void
    setScaleFactor(double scaleFactor)
    Set the scale factor.
    void
    setTranslation(double x, double y)
    Specify translation after coordinate changes.
  • Method Details

    • getWidth

      int getWidth()
      Get the width of an image as an integer.
      Returns:
      the width of the image
    • getHeight

      int getHeight()
      Get the height of an image as an integer.
      Returns:
      the height of the image
    • getFloatWidth

      float getFloatWidth()
      Get the width of an image .
      Returns:
      the width in image user-space coordinates
    • getFloatHeight

      float getFloatHeight()
      Get the height of an image.
      Returns:
      the height in user-space coordinates
    • getScaleFactor

      double getScaleFactor()
      Set the scale factor. A rendered model will be scaled by this amount. When the scale factor is 1.0, a unit distance in the model is a unit distance in the image's user space (e.g. 1/72 of an inch on a display). The scale factor is applied after any rotation or translation. The coordinate whose post-rotation and post-translation value is (0.0, 0.0, 0.0) will appear at the image's origin after scaling.
      Returns:
      the scale factor
    • setScaleFactor

      void setScaleFactor(double scaleFactor)
      Set the scale factor. A rendered model will be scaled by this amount. When the scale factor is 1.0, a unit distance in the model is a unit distance in the image's user space (e.g. 1/72 of an inch on a display). The scale factor is applied after any rotation or translation. The coordinate whose post-rotation and post-translation value is (0.0, 0.0, 0.0) will appear at the image's origin after scaling.
      Parameters:
      scaleFactor - the scale factor
    • getXOrigin

      float getXOrigin()
      Get the X coordinate of the origin. The origin is the point on the image that will correspond to points in the model for which x = 0.0 and y = 0.0. Note that user space follows the standard Java convention in which increasing X values go 'right' on an image and increasing Y values do 'down'.
      Returns:
      the X coordinate of the origin in the image's user space
    • getYOrigin

      float getYOrigin()
      Get the Y coordinate of the origin Note that user space follows the standard Java convention in which increasing X values go 'right' on an image and increasing Y values do 'down'.
      Returns:
      the Y coordinate of the origin in the image's user space
    • setOrigin

      void setOrigin(int x, int y)
      Set the origin given integer coordinates. The origin is the point on the image that will correspond to points in the model for which x = 0.0 and y = 0.0. Note that user space follows the standard Java convention in which increasing X values go 'right' on an image and increasing Y values do 'down'.
      Parameters:
      x - the X coordinate in the image's user space
      y - the Y coordinate in the image's user space
    • setOrigin

      void setOrigin(double x, double y)
      Set the origin give double-precision coordinates The origin is the point on the image that will correspond to points in the model for which x = 0.0 and y = 0.0. Note that user space follows the standard Java convention in which increasing X values go 'right' on an image and increasing Y values do 'down'.
      Parameters:
      x - the X coordinate in the image's user space
      y - the Y coordinate in the image's user space
    • setOrigin

      void setOrigin(float x, float y)
      Set the origin given floating-point coordinates. The origin is the point on the image that will correspond to points in the model for which x = 0.0 and y = 0.0. Note that user space follows the standard Java convention in which increasing X values go 'right' on an image and increasing Y values do 'down'.
      Parameters:
      x - the user-space x-coordinate of the origin
      y - the user-space y-coordinate of the origin
    • setOrigin

      void setOrigin(int offset)
      Set the origin given an integer offset. The origin is the point on the image that will correspond to points in the model for which x = 0.0 and y = 0.0. When the offset is non-negative, the offset gives the distance in user-space coordinates, for both the x coordinate and the y coordinate, from the lower left corner of the image to the position of the origin. When negative, the absolute value gives the distances from the upper right corner of the image.
      Parameters:
      offset - the offset
    • setOrigin

      void setOrigin(double offset)
      Set the origin given a double-precision offset. The origin is the point on the image that will correspond to points in the model for which x = 0.0 and y = 0.0. When the offset is non-negative, the offset gives the distance in user-space coordinates, for both the x coordinate and the y coordinate, from the lower left corner of the image to the position of the origin. When negative, the absolute value gives the distances from the upper right corner of the image.
      Parameters:
      offset - the offset
    • setOrigin

      void setOrigin(float offset)
      Set the origin given an offset. The origin is the point on the image that will correspond to points in the model for which x = 0.0 and y = 0.0. When the offset is non-negative, the offset gives the distance in user-space coordinates, for both the x coordinate and the y coordinate, from the lower left corner of the image to the position of the origin. When negative, the absolute value gives the distances from the upper right corner of the image.
      Parameters:
      offset - the offset
    • setOriginByFraction

      void setOriginByFraction(double offset)
      Set the origin given a double-precision fractional offset. The origin is the point on the image that will correspond to points in the model for which x = 0.0 and y = 0.0. The fractional offset sets the offset to the value of offset multiplied by the width and height for the x coordinate and y coordinate respectively. If the offset is positive, the offset is from the lower-left corner of an image. If negative, the offset is from the upper right corner.
      Parameters:
      offset - the fractional offset in the range (-1.0, 1.0)
    • setOriginByFraction

      void setOriginByFraction(float offset)
      Set the origin given a single-precision fractional offset. The origin is the point on the image that will correspond to points in the model for which x = 0.0 and y = 0.0. The fractional offset sets the offset to the value of offset multiplied by the width and height for the x coordinate and y coordinate respectively. If the offset is positive, the offset is from the lower-left corner of an image. If negative, the offset is from the upper right corner.
      Parameters:
      offset - the fractional offset in the range (-1.0, 1.0)
    • setOrigin

      void setOrigin()
      Set the origin to a default value. The origin is the point on the image that will correspond to points in the model for which x = 0.0 and y = 0.0. The default will place the origin in the center of an image.
    • getPhi

      double getPhi()
      Get the Eulerian angle phi for a coordinate rotation. A coordinate rotation and translation refers to a new position and orientation of the coordinate system assuming the model is held stationary. The model will appear to rotate and translate in the opposite direction from that specified by these Eulerian angles.
      Returns:
      the value of phi in radians
      See Also:
    • getTheta

      double getTheta()
      Get the Eulerian angle theta for a coordinate rotation. A coordinate rotation and translation refers to a new position and orientation of the coordinate system assuming the model is held stationary. The model will appear to rotate and translate in the opposite direction from that specified by these Eulerian angles.
      Returns:
      the value of theta in radians
      See Also:
    • getPsi

      double getPsi()
      Get the Eulerian angle psi for a coordinate rotation. A coordinate rotation and translation refers to a new position and orientation of the coordinate system assuming the model is held stationary. The model will appear to rotate and translate in the opposite direction from that specified by these Eulerian angles.
      Returns:
      the value of psi in radians
      See Also:
    • setCoordRotation

      void setCoordRotation(double phi, double theta, double psi)
      Rotate the Model3D coordinates. When all values are zero, the original z axis is perpendicular to an image, the original x axis is horizontal, and the original y axis is vertical, all following the standard mathematical convention that the x axis goes from left to right, the y axis goes from bottom to top. The z axis points towards the viewer.

      The Eulerian angles follow the convention used in Goldstein, "Classical Mechanics": phi is the angle the x-axis rotates with positive values of phi indicating a counter-clockwise rotation when viewed from positive values of z towards the plane in which z=0. Theta then indicates a rotation about the new x axis, and psi indicates a rotation about the final z axis.

      Note that the coordinate system is being rotated, not the object being displayed, and that the rotation applies from the original axes, as opposed to being applied incrementally.

      Parameters:
      phi - the Eulerian angle phi in radians
      theta - the Eulerian angle theta in radians
      psi - the Eulerian angle psi in radians
    • getRotationXOrigin

      double getRotationXOrigin()
      Get the X coordinate of the origin/target point for a coordinate rotation. This is the first argument to the most recent call to setRotationOrigin(double,double,double) or setRotationOrigin(double,double,double,boolean).
      Returns:
      the X coordinate in the model's coordinate system
    • getRotationYOrigin

      double getRotationYOrigin()
      Get the Y coordinate of the origin/target point for a coordinate rotation. This is the first argument to the most recent call to setRotationOrigin(double,double,double) or setRotationOrigin(double,double,double,boolean).
      Returns:
      the Y coordinate in the model's coordinate system
    • getRotationZOrigin

      double getRotationZOrigin()
      Get the Z coordinate of the origin/target point for a coordinate rotation. This is the second argument to the most recent call to setRotationOrigin(double,double,double) or setRotationOrigin(double,double,double,boolean).
      Returns:
      the Z coordinate in the model's coordinate system
    • moveOriginAfterRotation

      boolean moveOriginAfterRotation()
      Determine if the transformed origin for (0,0,0) will be moved to the coordinate origin after the rotation is completed. This is the value of the last argument to the most recent call to setRotationOrigin(double,double,double,boolean), which is also called by the three-argument method setRotationOrigin(double,double,double) with a final argument of false. When false, the rotation occurs about a specified point. When true, the rotation in effect occurs around (0, 0, 0) and then (0, 0, 0) is moved to the rotation origin.
      Returns:
      true if it will be moved; false if not
      See Also:
    • setRotationOrigin

      void setRotationOrigin(double x, double y, double z)
      Move the rotation origin for a coordinate rotation. The default performs a coordinate rotation about the point (0,0,0). For another value, the point (x, y, z) before the rotation will have the same value in the new coordinate system: (x,y,z) = (x',y',z'). The x, y, and z arguments refer to the model's coordinate system.
      Parameters:
      x - the x coordinate about which to perform the rotation
      y - the y coordinate about which to perform the rotation
      z - the z coordinate about which to perform the rotation
    • setRotationOrigin

      void setRotationOrigin(double x, double y, double z, boolean move)
      Move the rotation origin for a coordinate rotation with options. Setting the 'move' argument to true is useful when you want to rotate an object and place the previous origin at a specific location. The x, y, and z arguments refer to the model's coordinate system.
      Parameters:
      x - the x coordinate about which to perform the rotation
      y - the y coordinate about which to perform the rotation
      z - the z coordinate about which to perform the rotation
      move - false if (x,y,z) will have the same value after the rotation; true if the point (0,0,0) in the old coordinate system will be mapped to the point (x,y,z) in the new coordinate system after the rotation is complete.
      See Also:
    • getXTranslation

      double getXTranslation()
      Get the coordinate translation in the X direction that will be applied after other coordinate transformations are completed. (Note: because the coordinate system is being translated, objects will appear to move in the opposite direction).
      Returns:
      the translation in the X direction
    • getYTranslation

      double getYTranslation()
      Get the coordinate translation in the Y direction that will be applied after other coordinate transformations are completed. (Note: because the coordinate system is being translated, objects will appear to move in the opposite direction).
      Returns:
      the translation in the Y direction
    • setTranslation

      void setTranslation(double x, double y)
      Specify translation after coordinate changes. After other coordinate transformations are complete, the coordinate system in which a Model3D object is shown may be translated by an amount x in the x direction and an amount y in the y direction. The object displayed will appear to move in the opposite direction.
      Parameters:
      x - the x-axis translation
      y - the y-axis translation
    • getDelta

      double getDelta()
      Get the minimum triangle size for rendering. The size is measured in the x, y, and z directions. Larger triangles will be split into some number of smaller ones. Triangles will not be split if the value is zero.
      Returns:
      the minimum size
      See Also:
    • setDelta

      void setDelta(double delta)
      Set the minimum triangle size for rendering. The value of this parameter, if nonzero, specifies the maximum dimensions of a triangle that is to be rendered in the x, y, and z directions. If a triangle is larger, it is partitioned into a smaller set of triangles. This partitioning applies only during rendering. Setting the minimum size to a small, nonzero value can improve rendering by making the calculation of which triangle is in front of others more reliable. Too small a value, however, may slow rendering considerably. Units are those used for a triangle's X, Y, and Z coordinates.
      Parameters:
      delta - the triangle dimension limit; zero to indicate that triangles should not be split
    • getLightSourcePhi

      double getLightSourcePhi()
      Get the light-source parameter phi. The parameter partially determines the direction of the light source as described in the documentation for setLightSource.
      Returns:
      the light-source parameter phi in radians
      See Also:
    • getLightSourceTheta

      double getLightSourceTheta()
      Get the light-source parameter theta. The parameter partially determines the direction of the light source as described in the documentation for setLightSource.
      Returns:
      the light-source parameter theta in radians
      See Also:
    • setLightSource

      void setLightSource(double phi, double theta)
      Sets the direction to a light source. The default direction, in which theta=0, corresponds to a light source at infinity aimed vertically downwards towards the x-y plane. The brightness used for a triangle varies as the cosine of the angle between a vector pointing in the direction of the light source and a vector perpendicular to the plane of the triangle.
      Parameters:
      phi - the angle in radians about the z axis of the plane containing the z axis and a unit vector pointing towards the light source. If phi is zero, this plane includes the x axis and for non-zero theta, the unit vector will have a positive x component.
      theta - the angle in radians between a unit vector pointing towards the light source makes and with a vector parallel to the z axis.
    • getColorFactor

      double getColorFactor()
      Get the color factor. After coordinate transformations, the red, blue, and green components of the color of an object will be scaled depending on its height so that, for the same orientation, triangles at with the lowest values of 'z' will be dimmer than those with the maximum value of 'z' by this factor. A value of zero indicates that the color factor will be ignored. A value larger than 1.0 will result in the multiple Z values being rendered in black, but with more color separation for higher Z values.
      Returns:
      the color factor
      See Also:
    • setColorFactor

      void setColorFactor(double factor)
      Set the color factor. After coordinate transformations, the red, blue, and green components of the color of an object will be scaled depending on its height so that, for the same orientation, triangles at with the lowest values of 'z' will be dimmer than those with the maximum value of 'z' by this factor. If the value is 1.0, the smallest z value of the object will be rendered as black. A value of 0.0 indicates that the color factor will be ignored. A value larger than 1.0 will result in the multiple Z values being rendered in black, but with more color separation for higher Z values.

      This is intended to help emphasize differences along the 'z' axis that would normally be hard to discern visually.

      Parameters:
      factor - the color factor given as a non-negative number
    • getNormalFactor

      double getNormalFactor()
      Get the normal factor After a coordinate transformation, the normal factor is used to reduce the color factor towards 0.0 when a surface segment' is not aligned with the Z axis. If the Z component of the segment's normal vector is nz and the normal factor is larger than 0.0, the color factor is multiplied by exp(-(1.0-nz)/normalFactor). Since the normal vector has a length of 1.0, when the normal vector does not point in the positive Z direction, nz will be less than 1.0 and the color factor will be reduced.
      Returns:
      the normal factor; 0.0 if there is none
    • setNormalFactor

      void setNormalFactor(double factor)
      Set the normal factor. After a coordinate transformation, the normal factor is used to reduce the color factor towards 0.0 when a surface segment' is not aligned with the Z axis. If the Z component of the segment's normal vector is nz and the normal factor is larger than 0.0, the color factor is multiplied by exp(-(1.0-nz)/normalFactor). Since the normal vector has a length of 1.0, when the normal vector does not point in the positive Z direction, nz will be less than 1.0 and the color factor will be reduced.
      Parameters:
      factor - the normal factor; 0.0 or negative if there is none
    • getBacksideColor

      Color getBacksideColor()
      Get the color for the the side of a triangle that should not be visible due to being on the inside of a closed manifold.
      Returns:
      the color
    • setBacksideColor

      void setBacksideColor(Color c)
      Set the color for the side of a triangle that should not be visible due to being on the inside of a closed manifold. This is useful for debugging a model: one class of errors results in a triangle having the wrong orientation, and setting this parameter can help indicate where the problem is in the model.
      Parameters:
      c - the color; null if a color is not set
    • getEdgeColor

      Color getEdgeColor()
      Get the color used to indicate the edges of a triangle
      Returns:
      the color or null to indicate that edges will not be shown
    • setEdgeColor

      void setEdgeColor(Color c)
      Set the color to use to use to draw the edges of triangles.
      Parameters:
      c - the color; null if edges should not be displayed
    • getDefaultSegmentColor

      Color getDefaultSegmentColor()
      Get the color to use for line segments explicitly added or associated with triangles added for rendering. The phrase "[line segments] associated with triangles" refers to the additional edges of triangles that were added during the rendering process to minimize z-order issues that can occur when at least one edge of a triangle is abnormally large. Such triangles may be added when setDelta(double) is called with a non-zero argument.
      Returns:
      the color; null if the line segments should not be shown
    • setDefaultSegmentColor

      void setDefaultSegmentColor(Color c)
      Set the color to use for line segments explicitly added or associated with triangles added for rendering. The phrase "[line segments] associated with triangles" refers to the additional edges of triangles that were added during the rendering process to minimize z-order issues that can occur when at least one edge of a triangle is abnormally large. Such triangles may be added when setDelta(double) is called with a non-zero argument.
      Parameters:
      c - the color; null if line segments should not be displayed
    • getDefaultBacksideSegmentColor

      Color getDefaultBacksideSegmentColor()
      Get the default backside color to use for line segments associated with triangles added for rendering. The phrase "[line segments] associated with triangles" refers to the additional edges of triangles that were added during the rendering process to minimize z-order issues that can occur when at least one edge of a triangle is abnormally large. Such triangles may be added when setDelta(double) is called with a non-zero argument.
      Returns:
      the color; null if the line segments should not be shown
    • setDefaultBacksideSegmentColor

      void setDefaultBacksideSegmentColor(Color c)
      Set the default backside color to use for line segments associated with triangles added for rendering. The phrase "[line segments] associated with triangles" refers to the additional edges of triangles that were added during the rendering process to minimize z-order issues that can occur when at least one edge of a triangle is abnormally large. Such triangles may be added when setDelta(double) is called with a non-zero argument.
      Parameters:
      c - the color; null if these line segments should not be displayed
    • getImageData

      Model3D.ImageDataImpl getImageData()
      Get the corresponding ImageDataImpl.
      Returns:
      the corresponding ImageDataImpl
    • reset

      void reset()
      Reset to default values.