com.pixelmed.geometry

## Class LocalizerPoster

- java.lang.Object
- - com.pixelmed.geometry.LocalizerPoster

-     public abstract class LocalizerPoster
      extends java.lang.Object

  An abstract class that provides the basis for posting the position of specified slices and volumes on (usually orthogonal) localizer images.

  This base class provides the interface, common storage and various utility methods, and specific methods of performing the localization operation are performed by concrete sub-classes, instantiated through a factory class.

  Typically this would b used as follows, to get outlines in the form of a vector of shapes whose coordinates are those of the localizer image:

      GeometryOfSlice localizerGeometry = new GeometryOfSliceFromAttributeList(localizerAttributeList);
      GeometryOfSlice postImageGeometry = new GeometryOfSliceFromAttributeList(postImageAttributeList);
      LocalizerPoster localizerPoster = LocalizerPosterFactory.getLocalizerPoster(false,false);
      localizerPoster.setLocalizerGeometry(localizerGeometry);
      Vector shapes = localizerPoster.getOutlineOnLocalizerForThisGeometry(postImageGeometry);

  See Also:
    `LocalizerPosterFactory`, `GeometryOfSlice`, `GeometryOfSliceFromAttributeList`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected Vector3d` | `localizerColumn`
    `protected Tuple3d` | `localizerDimensions`
    `protected double[]` | `localizerDimensionsArray`
    `protected Vector3d` | `localizerNormal`
    `protected Vector3d` | `localizerRow`
    `protected Point3d` | `localizerTLHC`
    `protected Tuple3d` | `localizerVoxelSpacing`
    `protected double[]` | `localizerVoxelSpacingArray`
    `protected Matrix3d` | `rotateIntoLocalizerSpace`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected static boolean` | `classifyCornersIntoEdgeCrossingZPlane(Point3d startCorner, Point3d endCorner)`
    `protected void` | `doCommonConstructorStuff()`
    `protected java.util.Vector` | `drawLinesBetweenAnyPointsWhichIntersectPlaneWhereZIsZero(Point3d[] corners)`
    `protected java.util.Vector` | `drawOutlineOnLocalizer(Point3d[] corners)`
    `protected java.util.Vector` | `drawOutlineOnLocalizer(java.util.Vector corners)`
    `static java.awt.Rectangle` | `getBoundsOfContainedRectangle(Point3d[] containedRectangle, Point3d[] wholeRectangle, java.awt.Rectangle boundsOfWholeRectangle)`
    `static Point3d[]` | `getCornersOfSourceCubeInSourceSpace(Vector3d row, Vector3d column, Point3d originalTLHC, Tuple3d voxelSpacing, double sliceThickness, Tuple3d dimensions)` Get the corners of a volume in the 3D coordinate space of that volume.
    `static Point3d[]` | `getCornersOfSourceRectangleInSourceSpace(GeometryOfSlice g)` Get the corners of a slice in the 3D coordinate space of that slice.
    `static Point3d[]` | `getCornersOfSourceRectangleInSourceSpace(Vector3d row, Vector3d column, Point3d originalTLHC, Tuple3d voxelSpacing, Tuple3d dimensions)` Get the corners of a slice in the 3D coordinate space of that slice.
    `static Point3d[]` | `getIntersectionOfRectanglesInXYPlane(Point3d[] rect1, Point3d[] rect2)`
    `protected java.util.Vector` | `getIntersectionsOfCubeWithZPlane(Point3d[] corners)`
    `java.util.Vector` | `getOutlineOnLocalizerForThisGeometry(GeometryOfSlice geometry)` Get the shape on the localizer of a zero-thickness slice specified by the geometry of a 2D rectangle.
    `abstract java.util.Vector` | `getOutlineOnLocalizerForThisGeometry(Vector3d row, Vector3d column, Point3d tlhc, Tuple3d voxelSpacing, double sliceThickness, Tuple3d dimensions)` Get the shapes on the localizer of the specified slice.
    `java.util.Vector` | `getOutlineOnLocalizerForThisVolumeLocalization(SpectroscopyVolumeLocalization spectroscopyVolumeLocalization)` Get the shape on the localizer of one or more volume localization slabs.
    `protected Point3d` | `intersectLineBetweenTwoPointsWithPlaneWhereZIsZero(double[] a, double[] b)`
    `protected Point3d` | `intersectLineBetweenTwoPointsWithPlaneWhereZIsZero(Point3d aP, Point3d bP)`
    `void` | `setLocalizerGeometry(GeometryOfSlice geometry)` Established the geometry of the localizer image to be posted.
    `void` | `setLocalizerGeometry(Vector3d row, Vector3d column, Point3d tlhc, Tuple3d voxelSpacing, Tuple3d dimensions)` Established the geometry of the localizer image to be posted.
    `protected Point3d` | `transformPointFromSourceSpaceIntoLocalizerSpace(Point3d point)` Transform a point into the "viewport" defined by the localizer that we are an instance of.
    `static Point3d` | `transformPointFromSourceSpaceIntoSpecifiedSpace(Point3d point, Point3d tlhc, Vector3d row, Vector3d column)` Transform a point into the "viewport" defined by an origin and row and column vectors in the same 3D space, by shifting the points to the origin (TLHC) and rotating.
    `protected java.awt.geom.Point2D.Double` | `transformPointInLocalizerPlaneIntoImageSpace(Point3d point)` Project a point in localizer 3D space onto the plane of the localizer by ignoring the Z component, and return the X and Y coordinates as image-TLHC relative column and row offsets.
    `static Point3d[]` | `transformPointsFromSourceSpaceIntoSpecifiedSpace(Point3d[] points, Point3d tlhc, Vector3d row, Vector3d column)` Transform a set of points into the "viewport" defined by an origin and row and column vectors in the same 3D space, by shifting the points to the origin (TLHC) and rotating.
    `static void` | `validateDirectionCosines(Vector3d row, Vector3d column)` Check that the row and column vectors are unit vectors and are orthogonal.
    `static void` | `validateDirectionCosines(Vector3d row, Vector3d column, Vector3d normal)` Check that the row and column and slice direction vectors are unit vectors and are orthogonal.

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

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

- - ### Field Detail

    - #### localizerRow

          protected Vector3d localizerRow

    - #### localizerColumn

          protected Vector3d localizerColumn

    - #### localizerNormal

          protected Vector3d localizerNormal

    - #### localizerTLHC

          protected Point3d localizerTLHC

    - #### localizerVoxelSpacing

          protected Tuple3d localizerVoxelSpacing

    - #### localizerVoxelSpacingArray

          protected double[] localizerVoxelSpacingArray

    - #### localizerDimensions

          protected Tuple3d localizerDimensions

    - #### localizerDimensionsArray

          protected double[] localizerDimensionsArray

    - #### rotateIntoLocalizerSpace

          protected Matrix3d rotateIntoLocalizerSpace

  - ### Method Detail

    - #### validateDirectionCosines

          public static void validateDirectionCosines(Vector3d row,
                                                      Vector3d column)
                                               throws java.lang.IllegalArgumentException

      Check that the row and column vectors are unit vectors and are orthogonal.

      Parameters:
        `row` - the row direction cosines
        `column` - the column direction cosines
      Throws:
        `java.lang.IllegalArgumentException` - thrown if not

    - #### validateDirectionCosines

          public static void validateDirectionCosines(Vector3d row,
                                                      Vector3d column,
                                                      Vector3d normal)
                                               throws java.lang.IllegalArgumentException

      Check that the row and column and slice direction vectors are unit vectors and are orthogonal.

      Parameters:
        `row` - the row direction cosines
        `column` - the column direction cosines
        `normal` - the normal to the row and column plane (the slice direction)
      Throws:
        `java.lang.IllegalArgumentException` - thrown if not

    - #### getCornersOfSourceRectangleInSourceSpace

          public static Point3d[] getCornersOfSourceRectangleInSourceSpace(GeometryOfSlice g)

      Get the corners of a slice in the 3D coordinate space of that slice.

      Parameters:
        `g` - the geometry of a slice
      Returns:
        an array of four points that are the tlhc,trhc, brhc, blhc of the slice

    - #### getCornersOfSourceRectangleInSourceSpace

          public static Point3d[] getCornersOfSourceRectangleInSourceSpace(Vector3d row,
                                                                           Vector3d column,
                                                                           Point3d originalTLHC,
                                                                           Tuple3d voxelSpacing,
                                                                           Tuple3d dimensions)

      Get the corners of a slice in the 3D coordinate space of that slice.

      Parameters:
        `row` - the direction of the row as X, Y and Z components (direction cosines, unit vector) LPH+
        `column` - the direction of the column as X, Y and Z components (direction cosines, unit vector) LPH+
        `originalTLHC` - the position of the top left hand corner of the slice as a point (X, Y and Z) LPH+
        `voxelSpacing` - the row and column spacing and the slice interval
        `dimensions` - the row and column dimensions and 1 for the third dimension
      Returns:
        an array of four points that are the tlhc,trhc, brhc, blhc of the slice

    - #### getCornersOfSourceCubeInSourceSpace

          public static Point3d[] getCornersOfSourceCubeInSourceSpace(Vector3d row,
                                                                      Vector3d column,
                                                                      Point3d originalTLHC,
                                                                      Tuple3d voxelSpacing,
                                                                      double sliceThickness,
                                                                      Tuple3d dimensions)

      Get the corners of a volume in the 3D coordinate space of that volume.

      Parameters:
        `row` - the direction of the row as X, Y and Z components (direction cosines, unit vector) LPH+
        `column` - the direction of the column as X, Y and Z components (direction cosines, unit vector) LPH+
        `originalTLHC` - the position of the top left hand corner of the slice as a point (X, Y and Z) LPH+
        `voxelSpacing` - the row and column spacing and the slice interval
        `sliceThickness` - the slice thickness
        `dimensions` - the row and column dimensions and number of frames for the third dimension
      Returns:
        an array of eight points that are the tlhcT, trhcT, brhcT, blhcT, tlhcB, trhcB, brhcB, blhcB of the volume

    - #### getIntersectionOfRectanglesInXYPlane

          public static Point3d[] getIntersectionOfRectanglesInXYPlane(Point3d[] rect1,
                                                                       Point3d[] rect2)

    - #### getBoundsOfContainedRectangle

          public static java.awt.Rectangle getBoundsOfContainedRectangle(Point3d[] containedRectangle,
                                                                         Point3d[] wholeRectangle,
                                                                         java.awt.Rectangle boundsOfWholeRectangle)

    - #### transformPointsFromSourceSpaceIntoSpecifiedSpace

          public static Point3d[] transformPointsFromSourceSpaceIntoSpecifiedSpace(Point3d[] points,
                                                                                   Point3d tlhc,
                                                                                   Vector3d row,
                                                                                   Vector3d column)

      Transform a set of points into the "viewport" defined by an origin and row and column vectors in the same 3D space, by shifting the points to the origin (TLHC) and rotating.

      Parameters:
        `points` - an array of 3D points to be transformed
        `tlhc` - the position of the top left hand corner of the slice as a point (X, Y and Z) LPH+
        `row` - the direction of the row as X, Y and Z components (direction cosines, unit vector) LPH+
        `column` - the direction of the column as X, Y and Z components (direction cosines, unit vector) LPH+
      Returns:
        a new array of transformed points

    - #### transformPointFromSourceSpaceIntoSpecifiedSpace

          public static Point3d transformPointFromSourceSpaceIntoSpecifiedSpace(Point3d point,
                                                                                Point3d tlhc,
                                                                                Vector3d row,
                                                                                Vector3d column)

      Transform a point into the "viewport" defined by an origin and row and column vectors in the same 3D space, by shifting the points to the origin (TLHC) and rotating.

      Parameters:
        `point` - a 3D point to be transformed
        `tlhc` - the position of the top left hand corner of the slice as a point (X, Y and Z) LPH+
        `row` - the direction of the row as X, Y and Z components (direction cosines, unit vector) LPH+
        `column` - the direction of the column as X, Y and Z components (direction cosines, unit vector) LPH+
      Returns:
        a new, transformed point

    - #### transformPointFromSourceSpaceIntoLocalizerSpace

          protected Point3d transformPointFromSourceSpaceIntoLocalizerSpace(Point3d point)

      Transform a point into the "viewport" defined by the localizer that we are an instance of.

      Parameters:
        `point` - a 3D point to be transformed
      Returns:
        a new, transformed point

    - #### transformPointInLocalizerPlaneIntoImageSpace

          protected java.awt.geom.Point2D.Double transformPointInLocalizerPlaneIntoImageSpace(Point3d point)

      Project a point in localizer 3D space onto the plane of the localizer by ignoring the Z component, and return the X and Y coordinates as image-TLHC relative column and row offsets.

      Will return sub-pixel values ranging from 0.5 to 0.5 less than the maximum dimensions of the image, which allows points at the very edges of the rendered image to be drawn (e.g. a column of 0.5 will draw at the extreme left and a column of 255.5 will draw at the extreme right of a 256 pixel wide image (whereas 256.0 will not, though 0.0 will).

      Parameters:
        `point` - the point in 3D localizer space, the Z coordinate of which is ignored
      Returns:
        an array of 2 values in which the column, then the row location on the image is returned

    - #### drawOutlineOnLocalizer

          protected java.util.Vector drawOutlineOnLocalizer(java.util.Vector corners)

    - #### drawOutlineOnLocalizer

          protected java.util.Vector drawOutlineOnLocalizer(Point3d[] corners)

    - #### intersectLineBetweenTwoPointsWithPlaneWhereZIsZero

          protected Point3d intersectLineBetweenTwoPointsWithPlaneWhereZIsZero(double[] a,
                                                                               double[] b)

    - #### intersectLineBetweenTwoPointsWithPlaneWhereZIsZero

          protected Point3d intersectLineBetweenTwoPointsWithPlaneWhereZIsZero(Point3d aP,
                                                                               Point3d bP)

    - #### drawLinesBetweenAnyPointsWhichIntersectPlaneWhereZIsZero

          protected java.util.Vector drawLinesBetweenAnyPointsWhichIntersectPlaneWhereZIsZero(Point3d[] corners)

    - #### classifyCornersIntoEdgeCrossingZPlane

          protected static boolean classifyCornersIntoEdgeCrossingZPlane(Point3d startCorner,
                                                                         Point3d endCorner)

    - #### getIntersectionsOfCubeWithZPlane

          protected java.util.Vector getIntersectionsOfCubeWithZPlane(Point3d[] corners)

    - #### doCommonConstructorStuff

          protected void doCommonConstructorStuff()

    - #### setLocalizerGeometry

          public void setLocalizerGeometry(Vector3d row,
                                           Vector3d column,
                                           Point3d tlhc,
                                           Tuple3d voxelSpacing,
                                           Tuple3d dimensions)

      Established the geometry of the localizer image to be posted.

      Parameters:
        `row` - the unit vector (direction cosine) of the row direction in the DICOM coordinate system
        `column` - the unit vector (direction cosine) of the row direction in the DICOM coordinate system
        `tlhc` - the position in the DICOM coordinate system of the center of the top left hand corner of the image
        `voxelSpacing` - the row and column pixel spacing in mm
        `dimensions` - the number of rows and columns

    - #### setLocalizerGeometry

          public void setLocalizerGeometry(GeometryOfSlice geometry)

      Established the geometry of the localizer image to be posted.

      Parameters:
        `geometry` -

    - #### getOutlineOnLocalizerForThisGeometry

          public abstract java.util.Vector getOutlineOnLocalizerForThisGeometry(Vector3d row,
                                                                                Vector3d column,
                                                                                Point3d tlhc,
                                                                                Tuple3d voxelSpacing,
                                                                                double sliceThickness,
                                                                                Tuple3d dimensions)

      Get the shapes on the localizer of the specified slice.

      Parameters:
        `row` - the unit vector (direction cosine) of the row direction in the DICOM coordinate system
        `column` - the unit vector (direction cosine) of the row direction in the DICOM coordinate system
        `tlhc` - the position in the DICOM coordinate system of the center of the top left hand corner pixel of the slice
        `voxelSpacing` - the row and column and slice interval in mm
        `sliceThickness` - the slice thickness in mm
        `dimensions` - the number of rows and columns and slices
      Returns:
        vector of shapes `java.awt.Shape` to be drawn in the localizer row and column coordinates

    - #### getOutlineOnLocalizerForThisGeometry

          public final java.util.Vector getOutlineOnLocalizerForThisGeometry(GeometryOfSlice geometry)

      Get the shape on the localizer of a zero-thickness slice specified by the geometry of a 2D rectangle.

      Parameters:
        `geometry` -
      Returns:
        vector of shapes `java.awt.Shape` to be drawn in the localizer row and column coordinates

    - #### getOutlineOnLocalizerForThisVolumeLocalization

          public final java.util.Vector getOutlineOnLocalizerForThisVolumeLocalization(SpectroscopyVolumeLocalization spectroscopyVolumeLocalization)

      Get the shape on the localizer of one or more volume localization slabs.

      Parameters:
        `spectroscopyVolumeLocalization` -
      Returns:
        vector of shapes `java.awt.Shape` to be drawn in the localizer row and column coordinates