Transform3D
vmm3d.core3D

Class Transform3D

  • All Implemented Interfaces:
    Cloneable


    public class Transform3Dextends Transform
    A transform that encodes a 3D view of an exhibit and the projection of that view onto a 2D view plane. This class inherits the window-to-viewport transformation from its superclass, and adds a 3D viewing transformation.

    The projection is defined by three unit vectors: ViewDirection, ImagePlaneYDirection, and ImagePlaneXDirection. The ViewDirection is determined by the viewpoint that is specified for the view; ViewDirection is a unit vector that points in the direction from the viewpoint towards (0,0,0). The ViewDirection determines the viewing plane, which is a plane through (0,0,0) normal to the view direction. The ImagePlaneYDirection vector is obtained by projecting a "view up" vector onto the viewing plane, and then normalizing the projection. Initially, the view up vector is (0,0,1) or, if (0,0,1) almost normal to the view plane, (0,1,0). When the viewpoint is modified, the new ImagePlaneYDirection is obtained by using the previous ImagePlaneYDirection as the view up vector, if possible. After the ViewDirection and ImagePlaneYDirection are determined, the ImagePlaneXDirection is simply the cross product of these two vectors.

    The transform also has an associated "focalLength" which is set to the distance of the viewpoint from the origin, and a clipDistance, which is set to 25% of the focal length.

    A Transform3D fires a ChangeEvent when any part of the data that determines a 3D view is changed, such as the viewpoint.

    (Note that in the default view, the yz-plane projects onto the screen, and the x-axis is perpendicular to the screen. Nevertheless, the screen is thought of as being the xy-plane.) TODO: Possibly add support for using a point other than (0,0,0) as the view reference point; check how clip distance and focal length should be changed when viewpoint is changed.

    • Constructor Detail

      • Transform3D

        public Transform3D()
        Creates a Transform3D object with default viewpoint (20,0,0) and a default window with x and y ranges from -5 to 5.
      • Transform3D

        public Transform3D(Vector3D viewPoint)
        Creates a Transform3D object with a specified viewpoint and a default window with x and y ranges from -5 to 5.
        Parameters:
        viewPoint - the viewpoint of the transformation. If null, the default, (20,0,0), is used.
      • Transform3D

        public Transform3D(Vector3D viewPoint,           double nominalGraphicScale)
        Creates a Transform3D with a specifed viewpoint and with an xy-window determined by a given "graphic scale"
        Parameters:
        viewPoint - the viewpoint of the transformation. If null, the default, (20,0,0), is used.
        nominalGraphicScale - number of pixels per unit along the x- and y-axes, assuming that the size of the window is "normal". The normal size is given by a private constant NORMAL_SIZE, which is set to 600 at the time this comment was written.
      • Transform3D

        public Transform3D(Vector3D viewPoint,           double xmin,           double xmax,           double ymin,           double ymax)
        Construct a Transform3D with specified viewpoint and xy-window. The transformation is not fully determined until a viewport in the viewing plane is also specified; this is done when Transform#setUpDrawInfo(Graphics2D, int, int, int, int, boolean, boolean) is called. Note that when that method is called with its preserveAspect option set to true, the requested xmin, xmax, ymin, and ymax values might be adjusted to make the aspect ratio of the xy-window match the aspect ratio of the viewport.
        Parameters:
        viewPoint - The viewpoint of the transformation; if null, the default, (20,0,0), is used.
        xmin - the requested mimimum x-value for the transformation
        xmax - the requested maximum x-value for the transformation
        ymin - the requested mimimum y-value for the transformation
        ymax - the requested maximum y-value for the transformation
      • Transform3D

        public Transform3D(Transform tr)
        Construct a Transform3D with the same transform data as a specified transform. If the specfied transform is not a Transform3D, only the xy-window is copied; if it is a Transform3D, the 3D transformation data is also copied.
        Parameters:
        tr - the non-null transform whose data is to be copied.
    • Method Detail

      • getOrthographicProjection

        public boolean getOrthographicProjection()
        Returns true if the projection is an orthographic projection, or false if it is a perspective projection.
        See Also:
        setOrthographicProjection(boolean)
      • setOrthographicProjection

        public void setOrthographicProjection(boolean orthographicProjection)
        Sets whether the projection from 3D onto the viewplane should be a perspective projection or an orthographic projection.
        Parameters:
        orthographicProjection - "true" to use an orthographic projection; "false" to use a perspective projection.
      • setViewPoint

        public void setViewPoint(Vector3D viewPoint)
        Sets the viewpoint of the transformation. Note that when this method is called, a new transformation is defined which has a viewDirection specified by the viewpoint. This method then sets ImagePlaneYDirection and ImagePlaneXDirection by calling setImagePlaneYDirection(Vector3D) with the current ImagePlaneYDirection as parameter. In addition, the focal length is set to the distance of the viewpoint from (0,0,0), the clip distance is set to 0.25 times the focal length, and the ViewDirection is set to be a unit vector that points from the viewpoint towards (0,0,0).
        Parameters:
        viewPoint - the new viewpoint; if null, the default, (20,0,0), is used. The viewpoint cannot be (0,0,0), or the result will be an undefined transformation. Note that a copy of the viewPoint parameter is made (if it is non-null). (Note: Also turns off left/right eye selection, if in use.)
      • getViewPoint

        public Vector3D getViewPoint()
        Returns the current viewpoint of the transformation.
        Returns:
        a non-null vector that is the curent viewpoint.
      • setClipDistance

        public void setClipDistance(double clipDistance)
        Set the clip distance. This value is also set when the viewpoint is modified by setViewPoint(Vector3D). That method sets the clipDistance to 0.25 times the distance from the viewpoint to the origin.
      • getFocalLength

        public double getFocalLength()
        Gets the focal length, which is just the distance from the viewpoint to the origin.
      • getObjectDisplacementNormalToScreen

        public double getObjectDisplacementNormalToScreen()
        Get the amount by which object coordinates are displaed normal to the screen.
        See Also:
        setObjectDisplacementNormalToScreen(double)
      • setObjectDisplacementNormalToScreen

        public void setObjectDisplacementNormalToScreen(double objectDisplacementNormalToScreen)
        Set the amount by which object coordinates are displaed normal to the screen. Value is clamped so that its absolute value is less than or equal to 3/4 of the focal length. Before the object-to-view coordinate transformation is applied to any point, that point is displaced in the direction of the viewDirection vector by an amount equal to the setting of objectDisplacementNormalToScreen. The default value is zero. (In View3D, the amount is always 0 in monocular view modes, but can be chaned for the stereo views. BasicMouseTask3D allows the user to adjust this value for anaglyph views by holding down the shift key while dragging with the middle mouse button or by holding down the shift and option/ALT keys while dragging.) A ChangeEvent is generated when the value of this property is changed.
      • getImagePlaneXDirection

        public Vector3D getImagePlaneXDirection()
        Gets the current ImagePlaneXDirection, one of the three unit vectors that determine the projection.
        See Also:
        setImagePlaneYDirection(Vector3D)
      • getImagePlaneYDirection

        public Vector3D getImagePlaneYDirection()
        Gets the current ImagePlaneYDirection, one of the three unit vectors that determine the projection.
        See Also:
        setImagePlaneYDirection(Vector3D)
      • setImagePlaneYDirection

        public void setImagePlaneYDirection(Vector3D viewUp)
        Sets both the imagePlaneYDirection and imagePlaneXDirection so that these two vectors and the viewDirection (which points to the viewpoint) form an orthonomal system. (Note: Also turns off left/right eye selection, if in use.)
        Parameters:
        viewUp - the new imagePlaneYDirection, which will point upwards on the screen.
      • applyTransvection

        public void applyTransvection(Vector3D e1,                     Vector3D e2)
        Rotates vector e1 onto vector e2, resulting in a change of view. A ChangeEvent is generated
      • hasSameProjection

        public boolean hasSameProjection(Transform3D tr)
        Tests whether tr has the same projection from 3D to the view plane as this transform (but not necessarily the same window and viewport).
      • objectToViewCoords

        public void objectToViewCoords(Vector3D objectPoint,                      Vector3D viewCoords)
        Transform a point from object coordinates to viewing coordinates. After this method, the x- and y- coordinates of the resulting vector are coordinates for the viewing plane, while the z-coordinate encodes the distance of the object point from the viewing plane.
        Parameters:
        objectPoint - The non-null point whose coordinates are to be transformed. This vector is not modified.
        viewCoords - The non-null vector that will contain the result after this method is called. The previous components of this vector are replaced with the transformed version of objectPoint.
      • objectToViewCoords

        public Vector3D objectToViewCoords(Vector3D objectPoint)
        Transform a point in world coordinates to viewing coodinates. This is done by calling objectToViewCoords(Vector3D, Vector3D) with a newly created vector as its second argument, and then returning that vector.
        Parameters:
        objectPoint - The non-null point that is to be transformed
        Returns:
        The transformed version of objectPoint
      • objectToXYWindowCoords

        public void objectToXYWindowCoords(Vector3D objectPoint,                          Point2D p)
        Project a world-coordinate point onto the view plane. This is the same as taking just the x- and y-coordinate from the vector computed by objectToViewCoords(Vector3D, Vector3D).
        Parameters:
        objectPoint - a non-null vector whose corrdinates are to be transformed
        p - a non-null point whose coordinates will be set to the projected (x,y) point.
      • objectToXYWindowCoords

        public Point2D objectToXYWindowCoords(Vector3D objectPoint)
        Project a world-coordinate point onto the view plane. This is done by calling objectToDrawingCoords(Vector3D, Point2D) with a newly created Poin2D as its second parameter, and then returning that point.
      • objectToDrawingCoords

        public void objectToDrawingCoords(Vector3D objectPoint,                         Point2D drawingCoords)
        Transform a point given in world coordinates to a 2D point that can be used for drawing on the view plane. If the Transform.appliedTransform2D property is true, the result is the same as the result of objectToXYWindowCoords(Vector3D, Point2D), since regular xy window coordinates can be used for drawing directly. If the Transform.appliedTransform2D property is false, then the xy-coordinates are further transformed to the viewport (pixel) coordintates that are needed for drawing.
        Parameters:
        objectPoint - The point whose coordinates are to be projeted and transformed.
        drawingCoords - A pre-allocated non-null point to contain the result.
      • objectToDrawingCoords

        public Point2D objectToDrawingCoords(Vector3D objectPoint)
        Transform a point given in world coordinates to a 2D point that can be used for drawing on the view plane. This is done by applying objectToDrawingCoords(Vector3D, Point2D) to a newly allocated Point2D, and then returning that point.
      • objectToViewZ

        public double objectToViewZ(Vector3D objectPoint)
        Compute just the z-coordinate of a given point in view coordinates. This is the same as the z value in the vector that would be returned by objectToViewCoords(Vector3D)
        Parameters:
        objectPoint - the untransformed point in object coordinates
        Returns:
        the z-coordinate of the transformed point.

SCaVis 2.0 © jWork.ORG