Package edu.cnu.mdi.graphics.world

Class WorldGraphicsUtils

java.lang.Object
edu.cnu.mdi.graphics.world.WorldGraphicsUtils
public class WorldGraphicsUtils extends Object
Static utility methods for drawing and geometry operations in world coordinate space.

Coordinate systems

The MDI framework maintains two coordinate systems for each view:

  • World coordinates — the application's logical coordinate space (kilometres, degrees, arbitrary units, etc.), represented by double values and Point2D.Double.
  • Local (screen/pixel) coordinates — the pixel space of the rendered component, represented by int values and Point.

Conversion between the two spaces is handled by IContainer.worldToLocal(java.awt.Point, java.awt.geom.Point2D.Double) and IContainer.localToWorld(java.awt.Point, java.awt.geom.Point2D.Double). Every drawing method in this class accepts world coordinates and performs the conversion internally before issuing Java2D drawing calls.

Graphics context

All methods that perform drawing accept a Graphics2D context directly. No internal casting from Graphics is performed. The sole exception is drawImageOnQuad(java.awt.Graphics2D, java.awt.image.BufferedImage, java.awt.geom.Point2D.Double[], edu.cnu.mdi.container.IContainer), which calls Graphics.create() — a method declared on Graphics that returns Graphics — and therefore requires a cast back to Graphics2D for the child context. This is unavoidable and is the only cast in the class.

Null colors

Where fill and line colors are accepted separately, passing null suppresses that part of the drawing. For example, a null fill color produces an unfilled (outline-only) shape, and a null line color produces a filled shape with no outline.

Path support

Several methods operate on Path2D.Double objects. These methods support only straight-segment paths composed of SEG_MOVETO, SEG_LINETO, and SEG_CLOSE segments. If a path contains curve segments (SEG_QUADTO or SEG_CUBICTO) an IllegalArgumentException is thrown rather than producing silently incorrect results.

  • Field Details

    • DEFAULTSTROKE

      public static final Stroke DEFAULTSTROKE
      Default stroke: 1 pixel wide, solid style.

      Applied by setStyleDefaults(Graphics2D) and used as a fallback wherever no explicit stroke is specified.

  • Constructor Details

    • WorldGraphicsUtils

      public WorldGraphicsUtils()

  • Method Details

    • drawEtchedHorizontalWorldLine

      public static void drawEtchedHorizontalWorldLine(Graphics2D g2, IContainer container, double x, double y, double w, boolean lightAbove)
      Draw a horizontal "etched" line in world coordinates.

      An etched line is rendered as two parallel pixel-offset lines in contrasting colors to simulate a bevelled groove cut into a surface.

      Parameters:
      g2 - the graphics context
      container - the container defining the world-to-screen transform
      x - world X coordinate of the left end of the line
      y - world Y coordinate of the line
      w - width of the line in world units
      lightAbove - if true, the light color is drawn on top (simulating illumination from above); if false, the dark color is on top

    • drawEtchedVerticalWorldLine

      public static void drawEtchedVerticalWorldLine(Graphics2D g2, IContainer container, double x, double y, double h, boolean lightLeft)
      Draw a vertical "etched" line in world coordinates.

      An etched line is rendered as two parallel pixel-offset lines in contrasting colors to simulate a bevelled groove cut into a surface.

      Parameters:
      g2 - the graphics context
      container - the container defining the world-to-screen transform
      x - world X coordinate of the vertical line
      y - world Y coordinate of the top end of the line
      h - height of the line in world units
      lightLeft - if true, the light color is drawn on the left (simulating illumination from the left); if false, the dark color is on the left

    • drawWorldLine

      public static void drawWorldLine(Graphics2D g2, IContainer container, Point2D.Double wp0, Point2D.Double wp1, IStyled style)
      Draw a styled world line between two Point2D.Double endpoints.

      color, width, and dash pattern are taken from style.

      Parameters:
      g2 - the graphics context
      container - the container defining the world-to-screen transform
      wp0 - first endpoint in world coordinates
      wp1 - second endpoint in world coordinates
      style - source of line color, width, and style

    • drawWorldLine

      public static void drawWorldLine(Graphics2D g2, IContainer container, double x1, double y1, double x2, double y2, IStyled style)
      Draw a styled world line between two coordinate pairs.

      color, width, and dash pattern are taken from style.

      Parameters:
      g2 - the graphics context
      container - the container defining the world-to-screen transform
      x1 - world X of the first endpoint
      y1 - world Y of the first endpoint
      x2 - world X of the second endpoint
      y2 - world Y of the second endpoint
      style - source of line color, width, and style

    • drawWorldLine

      public static void drawWorldLine(Graphics2D g2, IContainer container, double x1, double y1, double x2, double y2, Color lineColor, float lineWidth, LineStyle lineStyle)
      Draw a world line with explicit color, width, and dash style.

      If lineColor is null the method returns immediately without drawing.

      Parameters:
      g2 - the graphics context
      container - the container defining the world-to-screen transform
      x1 - world X of the first endpoint
      y1 - world Y of the first endpoint
      x2 - world X of the second endpoint
      y2 - world Y of the second endpoint
      lineColor - line color; null suppresses drawing
      lineWidth - line width in pixels
      lineStyle - dash style

    • drawWorldLine

      public static void drawWorldLine(Graphics2D g2, IContainer container, Point2D.Double wp0, Point2D.Double wp1, Color lineColor)
      Draw a 1-pixel solid world line between two Point2D.Double endpoints.
      Parameters:
      g2 - the graphics context
      container - the container defining the world-to-screen transform
      wp0 - first endpoint in world coordinates
      wp1 - second endpoint in world coordinates
      lineColor - line color; null suppresses drawing

    • drawWorldLine

      public static void drawWorldLine(Graphics2D g2, IContainer container, double x1, double y1, double x2, double y2, Color lineColor)
      Draw a 1-pixel solid world line between two coordinate pairs.
      Parameters:
      g2 - the graphics context
      container - the container defining the world-to-screen transform
      x1 - world X of the first endpoint
      y1 - world Y of the first endpoint
      x2 - world X of the second endpoint
      y2 - world Y of the second endpoint
      lineColor - line color; null suppresses drawing

    • setStyleDefaults

      public static void setStyleDefaults(Graphics2D g2)
      Reset the graphics context to the MDI default drawing style.

      Sets the color to Color.black and the stroke to DEFAULTSTROKE (1 pixel wide, solid). Useful at the start of a draw method that does not receive explicit style parameters.

      Parameters:
      g2 - the graphics context to reset

    • getPixelEnds

      public static void getPixelEnds(IContainer container, Point p0, Point p1, Point2D.Double wp0, Point2D.Double wp1)
      Convert two world endpoints to their pixel equivalents.

      The results are written into the pre-allocated Point objects p0 and p1 to avoid allocating new objects on the critical drawing path.

      Parameters:
      container - the container defining the world-to-screen transform
      p0 - receives the pixel coordinates of wp0
      p1 - receives the pixel coordinates of wp1
      wp0 - first world endpoint
      wp1 - second world endpoint

    • getBounds

      public static Rectangle getBounds(IContainer container, Point2D.Double wp0, Point2D.Double wp1)
      Compute the pixel bounding rectangle for a line between two world points.

      The returned rectangle is expanded to a minimum size of 2 × 2 pixels so that nearly-horizontal and nearly-vertical lines still have a usable hit-test area.

      Parameters:
      container - the container defining the world-to-screen transform
      wp0 - first world endpoint
      wp1 - second world endpoint
      Returns:
      pixel bounding rectangle with a minimum dimension of 2

    • getBounds

      public static Rectangle getBounds(IContainer container, double x1, double y1, double x2, double y2)
      Compute the pixel bounding rectangle for a line between two world coordinate pairs.

      The returned rectangle is expanded to a minimum size of 2 × 2 pixels so that nearly-horizontal and nearly-vertical lines still have a usable hit-test area.

      Parameters:
      container - the container defining the world-to-screen transform
      x1 - world X of the first endpoint
      y1 - world Y of the first endpoint
      x2 - world X of the second endpoint
      y2 - world Y of the second endpoint
      Returns:
      pixel bounding rectangle with a minimum dimension of 2

    • signedSweepDeg

      public static double signedSweepDeg(Point2D.Double wpc, Point2D.Double wp1, Point2D.Double wp2)
      Compute the signed sweep angle in degrees from vector (wpc→wp1) to vector (wpc→wp2).

      Uses atan2(cross, dot) so the result carries the correct sign: positive for a counter-clockwise rotation, negative for clockwise.

      Parameters:
      wpc - the common origin of the two vectors (pivot point)
      wp1 - tip of the first vector; defines the start direction
      wp2 - tip of the second vector; defines the end direction
      Returns:
      signed sweep angle in degrees, in the range (-180, 180]

    • ccwSweepDeg

      public static double ccwSweepDeg(Point2D.Double wpc, Point2D.Double wp1, Point2D.Double wp2)
      Compute the counter-clockwise (CCW) sweep angle in degrees from vector (wpc→wp1) to vector (wpc→wp2).

      Unlike signedSweepDeg(java.awt.geom.Point2D.Double, java.awt.geom.Point2D.Double, java.awt.geom.Point2D.Double), this method always returns a value in [0, 360) so that major arcs are representable. For example, a signed angle of −60° becomes 300°.

      Parameters:
      wpc - the common origin of the two vectors (pivot point)
      wp1 - tip of the first vector; defines the start direction
      wp2 - tip of the second vector; defines the end direction
      Returns:
      CCW sweep angle in degrees, in the range [0, 360)

    • unwrapSweepDeg

      public static double unwrapSweepDeg(double prevUnwrapped, double signedNow)
      Unwrap a signed angle measurement so it varies continuously relative to a previous unwrapped angle, eliminating ±180° discontinuities.

      This is useful when accumulating a running sweep angle during an interactive drag: without unwrapping, crossing the ±180° boundary causes the accumulated angle to jump by 360°.

      Parameters:
      prevUnwrapped - the previous accumulated (unwrapped) angle, which may lie outside (-180, 180]
      signedNow - the new raw measurement from signedSweepDeg(java.awt.geom.Point2D.Double, java.awt.geom.Point2D.Double, java.awt.geom.Point2D.Double), in (-180, 180]
      Returns:
      the new unwrapped angle, adjusted to be continuous with prevUnwrapped

    • drawWorldRadArc

      public static void drawWorldRadArc(Graphics2D g2, IContainer container, double xc, double yc, double rmin, double rmax, double startAngle, double stopAngle, Color fillColor, Color lineColor, float lineWidth, LineStyle lineStyle)
      Draw a radar arc (annular sector) with explicit style parameters.

      A radar arc is defined by inner and outer radii (rmin, rmax) and an angular sweep from startAngle to stopAngle. The resulting shape is the region between the two arcs, closed by two radial edges.

      Parameters:
      g2 - the graphics context
      container - the container defining the world-to-screen transform
      xc - world X of the arc center
      yc - world Y of the arc center
      rmin - inner radius in world units
      rmax - outer radius in world units
      startAngle - start angle in degrees
      stopAngle - stop angle in degrees
      fillColor - fill color; null suppresses fill
      lineColor - outline color; null suppresses outline
      lineWidth - outline width in pixels
      lineStyle - outline dash style

    • drawWorldRadArc

      public static void drawWorldRadArc(Graphics2D g2, IContainer container, double xc, double yc, double rmin, double rmax, double startAngle, double stopAngle, Color fillColor, Color lineColor)
      Draw a radar arc (annular sector) with a 1-pixel solid outline.
      Parameters:
      g2 - the graphics context
      container - the container defining the world-to-screen transform
      xc - world X of the arc center
      yc - world Y of the arc center
      rmin - inner radius in world units
      rmax - outer radius in world units
      startAngle - start angle in degrees
      stopAngle - stop angle in degrees
      fillColor - fill color; null suppresses fill
      lineColor - outline color; null suppresses outline

    • drawWorldRadArc

      public static void drawWorldRadArc(Graphics2D g2, IContainer container, double xc, double yc, double rmin, double rmax, double startAngle, double stopAngle, IStyled style)
      Draw a radar arc (annular sector) using an IStyled source for fill color, line color, line width, and line style.
      Parameters:
      g2 - the graphics context
      container - the container defining the world-to-screen transform
      xc - world X of the arc center
      yc - world Y of the arc center
      rmin - inner radius in world units
      rmax - outer radius in world units
      startAngle - start angle in degrees
      stopAngle - stop angle in degrees
      style - source of fill color, line color, width, and style

    • drawImageOnQuad

      public static void drawImageOnQuad(Graphics2D g2, BufferedImage image, Point2D.Double[] wpoly, IContainer container)
      Draw a BufferedImage mapped onto an arbitrary world-coordinate quadrilateral.

      The image is mapped so that its top-left pixel aligns with wpoly[0], and the two edges adjacent to that corner determine the width and height directions. The method automatically selects which adjacent corner (wpoly[1] or wpoly[3]) is the width direction by matching the quad's aspect ratio to the image's aspect ratio.

      If the affine mapping has a negative determinant (i.e. the quad is mirror-reflected in local coordinates) the v-axis of the image mapping is flipped to prevent the image from being drawn upside down.

      Note on casting: this method calls Graphics.create(), which is declared on Graphics and returns Graphics. A cast to Graphics2D is therefore required for the child context. This is the only unavoidable cast in WorldGraphicsUtils.

      Parameters:
      g2 - the graphics context
      image - the image to draw; ignored if null
      wpoly - four world-coordinate corners in order: [w0, wa, w2, wb] where wa and wb are the corners adjacent to w0; ignored if null or fewer than 4 elements
      container - the container defining the world-to-screen transform

    • createWorldCircle

      public static Polygon createWorldCircle(IContainer container, double xc, double yc, double radius)
      Build a screen Polygon approximating a world-coordinate circle.

      The circle is approximated by 60 line segments.

      Parameters:
      container - the container defining the world-to-screen transform
      xc - world X of the center
      yc - world Y of the center
      radius - radius in world units
      Returns:
      polygon approximating the circle in pixel coordinates

    • createWorldDonut

      public static Polygon createWorldDonut(IContainer container, double xc, double yc, double minRadius, double maxRadius)
      Build a screen Polygon approximating a world-coordinate donut (annulus).

      If minRadius is less than TINY the inner ring is degenerate and the result degrades gracefully to a plain circle at maxRadius.

      Parameters:
      container - the container defining the world-to-screen transform
      xc - world X of the center
      yc - world Y of the center
      minRadius - inner radius in world units
      maxRadius - outer radius in world units
      Returns:
      polygon approximating the annulus in pixel coordinates

    • createWorldArc

      public static Polygon createWorldArc(IContainer container, double xc, double yc, double radius, double startAngle, double stopAngle)
      Build a screen Polygon approximating a world-coordinate arc (a portion of a circle's circumference).

      If the angular span |stopAngle - startAngle| is at least 360° − TINY, the full circle is returned via createWorldCircle(edu.cnu.mdi.container.IContainer, double, double, double).

      Parameters:
      container - the container defining the world-to-screen transform
      xc - world X of the center
      yc - world Y of the center
      radius - radius in world units
      startAngle - start angle in degrees
      stopAngle - stop angle in degrees
      Returns:
      polygon approximating the arc in pixel coordinates

    • drawWorldOval

      public static void drawWorldOval(Graphics2D g2, IContainer container, Rectangle2D.Double worldRectangle, Color fillColor, Color lineColor, float lineWidth, LineStyle lineStyle)
      Draw a world oval with explicit style parameters.

      The oval is inscribed within the axis-aligned world rectangle worldRectangle.

      Parameters:
      g2 - the graphics context
      container - the container defining the world-to-screen transform
      worldRectangle - bounding world rectangle of the oval
      fillColor - fill color; null suppresses fill
      lineColor - outline color; null suppresses outline
      lineWidth - outline width in pixels
      lineStyle - outline dash style

    • drawWorldOval

      public static void drawWorldOval(Graphics2D g2, IContainer container, Rectangle2D.Double worldRectangle, Color fillColor, Color lineColor)
      Draw a world oval with a 1-pixel solid outline.
      Parameters:
      g2 - the graphics context
      container - the container defining the world-to-screen transform
      worldRectangle - bounding world rectangle of the oval
      fillColor - fill color; null suppresses fill
      lineColor - outline color; null suppresses outline

    • drawWorldOval

      public static void drawWorldOval(Graphics2D g2, IContainer container, Rectangle2D.Double worldRectangle, IStyled style)
      Draw a world oval using an IStyled source for style properties.
      Parameters:
      g2 - the graphics context
      container - the container defining the world-to-screen transform
      worldRectangle - bounding world rectangle of the oval
      style - source of fill color, line color, width, and style

    • drawWorldRectangle

      public static void drawWorldRectangle(Graphics2D g2, IContainer container, Rectangle2D.Double worldRectangle, Color fillColor, Color lineColor, float lineWidth, LineStyle lineStyle)
      Draw a world rectangle with explicit style parameters.
      Parameters:
      g2 - the graphics context
      container - the container defining the world-to-screen transform
      worldRectangle - the world rectangle to draw
      fillColor - fill color; null suppresses fill
      lineColor - outline color; null suppresses outline
      lineWidth - outline width in pixels
      lineStyle - outline dash style

    • drawWorldRectangle

      public static void drawWorldRectangle(Graphics2D g2, IContainer container, Rectangle2D.Double worldRectangle, Color fillColor, Color lineColor)
      Draw a world rectangle with a 1-pixel solid outline.
      Parameters:
      g2 - the graphics context
      container - the container defining the world-to-screen transform
      worldRectangle - the world rectangle to draw
      fillColor - fill color; null suppresses fill
      lineColor - outline color; null suppresses outline

    • drawWorldRectangle

      public static void drawWorldRectangle(Graphics2D g2, IContainer container, Rectangle2D.Double worldRectangle, IStyled style)
      Draw a world rectangle using an IStyled source for style properties.
      Parameters:
      g2 - the graphics context
      container - the container defining the world-to-screen transform
      worldRectangle - the world rectangle to draw
      style - source of fill color, line color, width, and style

    • drawHighlightedRectangle

      public static void drawHighlightedRectangle(Graphics2D g2, IContainer container, Rectangle2D.Double wr, Color color1, Color color2)
      Draw the outline of a highlighted (marching-ants style) world rectangle.

      The outline alternates between color1 and color2 on successive pixels to produce a high-visibility selection indicator.

      Parameters:
      g2 - the graphics context
      container - the container defining the world-to-screen transform
      wr - the world rectangle to highlight
      color1 - first alternating color
      color2 - second alternating color

    • drawWorldPolygon

      public static void drawWorldPolygon(Graphics2D g2, IContainer container, WorldPolygon worldPolygon, Color fillColor, Color lineColor, float lineWidth)
      Draw a world polygon with a 1-pixel solid outline.
      Parameters:
      g2 - the graphics context
      container - the container defining the world-to-screen transform
      worldPolygon - the polygon in world coordinates
      fillColor - fill color; null suppresses fill
      lineColor - outline color; null suppresses outline
      lineWidth - outline width in pixels

    • drawWorldPolygon

      public static void drawWorldPolygon(Graphics2D g2, IContainer container, WorldPolygon worldPolygon, Color fillColor, Color lineColor, float lineWidth, LineStyle lineStyle)
      Draw a world polygon with explicit style parameters.
      Parameters:
      g2 - the graphics context
      container - the container defining the world-to-screen transform
      worldPolygon - the polygon in world coordinates
      fillColor - fill color; null suppresses fill
      lineColor - outline color; null suppresses outline
      lineWidth - outline width in pixels
      lineStyle - outline dash style

    • drawWorldText

      public static void drawWorldText(Graphics2D g2, IContainer container, double x, double y, String text, int dh, int dv)
      Draw a string anchored at a world coordinate with a pixel offset.

      The text is drawn using the current font and color of the graphics context. The pixel offset (dh, dv) is applied after the world-to-screen conversion, allowing fine-grained label placement relative to a world point.

      Parameters:
      g2 - the graphics context
      container - the container defining the world-to-screen transform
      x - world X of the text anchor
      y - world Y of the text anchor (baseline)
      text - the string to draw; ignored if null
      dh - additional horizontal pixel offset (positive = right)
      dv - additional vertical pixel offset (positive = down)

    • drawPath2D

      public static Polygon drawPath2D(Graphics2D g2, IContainer container, Path2D.Double path, IStyled style, boolean closed)
      Draw a straight-segment world path as either a closed polygon or an open polyline, deriving style from an IStyled object.
      Parameters:
      g2 - the graphics context
      container - the container defining the world-to-screen transform
      path - the world path (straight segments only)
      style - source of fill color, line color, width, and style
      closed - if true the path is drawn as a filled/outlined polygon; if false as an open polyline
      Returns:
      the pixel Polygon that was drawn, or null if the path had no vertices

    • drawPath2D

      public static Polygon drawPath2D(Graphics2D g2, IContainer container, Path2D.Double path, Color fillColor, Color lineColor, float lineWidth, LineStyle lineStyle, boolean closed)
      Draw a straight-segment world path as either a closed polygon or an open polyline, with explicit style parameters.

      Anti-aliasing is enabled for the duration of this call to produce smooth diagonal edges. If lineWidth is zero it is clamped to 0.5 so the path remains visible at all zoom levels.

      Parameters:
      g2 - the graphics context
      container - the container defining the world-to-screen transform
      path - the world path (straight segments only)
      fillColor - fill color; null suppresses fill (only meaningful when closed is true)
      lineColor - outline color; null suppresses outline
      lineWidth - outline width in pixels; clamped to 0.5 if zero
      lineStyle - outline dash style
      closed - if true the path is drawn as a filled/outlined polygon; if false as an open polyline
      Returns:
      the pixel Polygon that was drawn, or null if the path had no vertices

    • getPathPointCount

      public static int getPathPointCount(Path2D.Double path)
      Count the explicit vertex points in a straight-segment Path2D.Double.

      Vertices are contributed by SEG_MOVETO and SEG_LINETO segments only. SEG_CLOSE is ignored.

      Parameters:
      path - the path to inspect; null returns 0
      Returns:
      the number of MOVETO + LINETO vertices
      Throws:
      IllegalArgumentException - if the path contains curve segments

    • neededCapacity

      public static int neededCapacity(Path2D.Double path)
      Return the capacity (vertex count) needed to store a straight-segment path in a flat array.

      This is a convenience alias for getPathPointCount(Path2D.Double), intended for use at array-allocation sites to make the intent clear.

      Parameters:
      path - the path; null returns 0
      Returns:
      number of MOVETO + LINETO vertices
      Throws:
      IllegalArgumentException - if the path contains curve segments

    • getPoints

      public static ArrayList<Point2D.Double> getPoints(Path2D path)
      Extract the vertices of a straight-segment Path2D as a list.

      Vertices from SEG_MOVETO and SEG_LINETO are included. Iteration stops when a SEG_CLOSE is encountered if only one sub-path has been seen; multiple sub-paths are not supported.

      Parameters:
      path - the world path; must not be null
      Returns:
      a list of world vertices in path order
      Throws:
      IllegalArgumentException - if the path contains curve segments or multiple sub-paths

    • getPathPointAt

      public static Point2D.Double getPathPointAt(Path2D.Double path, int index)
      Return the world-coordinate vertex at the specified zero-based index in a straight-segment path.

      Only SEG_MOVETO and SEG_LINETO segments contribute vertices. SEG_CLOSE is ignored.

      Parameters:
      path - the world path; null returns null
      index - zero-based vertex index
      Returns:
      the vertex at index, or null if the index is out of range
      Throws:
      IllegalArgumentException - if the path contains curve segments

    • pathToPolygon

      public static Polygon pathToPolygon(IContainer container, Path2D.Double path)
      Convert a straight-segment world path to a screen Polygon.

      Each SEG_MOVETO and SEG_LINETO vertex is transformed from world to screen coordinates. SEG_CLOSE contributes no new vertex.

      Parameters:
      container - the container defining the world-to-screen transform; null returns null
      path - the world path; null returns null
      Returns:
      screen polygon, or null if there are no vertices
      Throws:
      IllegalArgumentException - if the path contains curve segments

    • pathToWorldPolygon

      public static Point2D.Double[] pathToWorldPolygon(Path2D.Double path)
      Extract the world-coordinate vertices of a straight-segment path as a new array.
      Parameters:
      path - the world path; null returns null
      Returns:
      array of world vertices, or null if the path has none
      Throws:
      IllegalArgumentException - if the path contains curve segments

    • pathToWorldPolygon

      public static void pathToWorldPolygon(Path2D.Double path, Point2D.Double[] wp)
      Copy the world-coordinate vertices of a straight-segment path into a pre-allocated array.

      Each element of wp must already be a non-null Point2D.Double. Iteration stops early if wp is full.

      Parameters:
      path - the world path; no-op if null
      wp - destination array of pre-allocated Point2D.Double objects; must not be null
      Throws:
      IllegalArgumentException - if the path contains curve segments

    • worldRectangleToPath

      public static Path2D.Double worldRectangleToPath(Rectangle2D.Double wr)
      Convert an axis-aligned world rectangle into a closed Path2D.Double.

      The path visits the four corners in order: top-left → bottom-left → bottom-right → top-right, then closes.

      Parameters:
      wr - the world rectangle; must not be null
      Returns:
      a closed path tracing the rectangle boundary

    • worldPolygonToPath

      public static Path2D.Double worldPolygonToPath(Point2D.Double[] points)
      Convert an array of world points into an open Path2D.Double.

      The first point becomes a moveTo; subsequent points become lineTo calls. The path is not closed.

      Parameters:
      points - world vertices; null returns null
      Returns:
      open world path, or null if points is null

    • getPoints

      public static Point2D.Double[] getPoints(Rectangle2D.Double wr)
      Return the four corners of a world rectangle as a point array.

      Corners are returned in order: top-left, bottom-left, bottom-right, top-right.

      Parameters:
      wr - the world rectangle; must not be null
      Returns:
      array of four Point2D.Double corners

    • intersection

      public static Point2D.Double intersection(Point2D.Double p1, Point2D.Double p2, Point2D.Double q1, Point2D.Double q2)
      Compute the intersection point of two line segments.

      Each segment is defined by two endpoints. Returns null if the segments are parallel (denominator near zero) or if the intersection lies outside either segment (parametric parameter outside [0, 1]).

      Parameters:
      p1 - first endpoint of segment 1
      p2 - second endpoint of segment 1
      q1 - first endpoint of segment 2
      q2 - second endpoint of segment 2
      Returns:
      the intersection point, or null if there is none within both segments

    • contains

      public static boolean contains(Point2D.Double[] poly, Point2D.Double wp)
      Test whether a world point lies inside a polygon.
      Parameters:
      poly - the polygon vertices; must not be null
      wp - the point to test; must not be null
      Returns:
      true if wp is inside poly

    • area

      public static double area(Point2D.Double[] poly)
      Compute the signed area of a polygon using the shoelace formula.

      A positive result indicates a counter-clockwise winding; negative indicates clockwise. Returns 0 for degenerate or collinear polygons.

      Parameters:
      poly - the polygon vertices; null or fewer than 3 vertices returns 0
      Returns:
      signed area in world-coordinate square units

    • getCentroid

      public static Point2D.Double getCentroid(Point2D.Double[] poly)
      Compute the centroid of a polygon.

      Uses the standard area-weighted formula. Returns null for degenerate polygons whose area is effectively zero.

      Parameters:
      poly - the polygon vertices; null returns null
      Returns:
      the centroid, or null if the polygon is degenerate

    • getCentroid

      public static Point2D.Double getCentroid(Path2D.Double path)
      Compute the centroid of a straight-segment path.
      Parameters:
      path - the world path; null returns null
      Returns:
      the centroid, or null if the path is degenerate

    • longestDiagonal

      public static double longestDiagonal(Point2D.Double focus, Point2D.Double[] poly)
      Compute the distance from focus to the farthest vertex of a polygon.

      This is used internally by polygonIntersection(java.awt.geom.Point2D.Double, double, java.awt.geom.Path2D.Double) to determine how long a ray must be to guarantee it crosses the polygon boundary.

      Parameters:
      focus - the reference point; null returns Double.NaN
      poly - the polygon vertices; null or empty returns Double.NaN
      Returns:
      the longest vertex distance, or Double.NaN if inputs are invalid

    • polygonIntersection

      public static Point2D.Double polygonIntersection(Point2D.Double p0, double azimuth, Path2D.Double path)
      Find the first intersection of a ray with a world path.

      The ray starts at p0 and radiates in the direction of azimuth. This is a convenience overload that converts the path to a polygon array before delegating to polygonIntersection(Point2D.Double, double, Point2D.Double[]).

      Parameters:
      p0 - the start point (typically inside the polygon)
      azimuth - direction of the ray in degrees (azimuth convention: 0 = north, 90 = east)
      path - the world path to intersect
      Returns:
      the first intersection point, or null if none found

    • polygonIntersection

      public static Point2D.Double polygonIntersection(Point2D.Double p0, double azimuth, Point2D.Double[] poly)
      Find the first intersection of a ray with a world polygon.

      The ray starts at p0 and extends twice the length of the longest vertex distance to ensure it crosses the boundary. The first segment intersection found is returned.

      This works reliably when p0 is inside a convex or mildly concave polygon. For very irregular polygons the "first" intersection may not be the geometrically nearest one.

      Parameters:
      p0 - the start point (typically inside the polygon)
      azimuth - direction of the ray in degrees (azimuth convention: 0 = north, 90 = east)
      poly - the polygon vertices
      Returns:
      the first intersection point, or null if none found

    • project

      public static void project(Point2D.Double focus, double distance, double angle, Point2D.Double wp)
      Project a world point by a distance and azimuth angle.

      The azimuth follows the compass convention: 0° is north (+Y), 90° is east (+X), 180° is south (−Y), 270° is west (−X).

      Parameters:
      focus - the origin point
      distance - the projection distance in world units
      angle - the direction in degrees (azimuth: 0 = north, 90 = east)
      wp - receives the projected point; must not be null

    • radiusPoint

      public static Point2D.Double radiusPoint(Point2D.Double center, double radius, double theta)
      Create a world point at a given distance and polar angle from a center.

      Unlike project(java.awt.geom.Point2D.Double, double, double, java.awt.geom.Point2D.Double), this method uses the standard mathematical polar angle convention (0° = east, 90° = north).

      Parameters:
      center - the origin point; must not be null
      radius - the distance from the center in world units
      theta - the angle in degrees (standard polar: 0 = east, 90 = north)
      Returns:
      the new world point

    • getRadArcPoints

      public static Point2D.Double[] getRadArcPoints(Point2D.Double wpc, Point2D.Double wp1, double arcAngle)
      Build an array of world points approximating a radar-arc sweep.

      The array begins at the center wpc, proceeds to wp1 (the first leg endpoint), then sweeps counter-clockwise by arcAngle degrees, using 60 interpolation steps. The first element is always the center; the remaining elements trace the arc.

      Parameters:
      wpc - the center of the arc
      wp1 - the first leg endpoint; the distance wpc→wp1 defines the radius
      arcAngle - the CCW sweep angle in degrees
      Returns:
      array of 60+ 2 world points (center + wp1 + arc samples)

    • getArcPoints

      public static Point2D.Double[] getArcPoints(Point2D.Double wpc, Point2D.Double wp1, double arcAngle)
      Build an array of world points approximating a simple arc sweep.

      Similar to getRadArcPoints(java.awt.geom.Point2D.Double, java.awt.geom.Point2D.Double, double) but does not include the center point. The array begins at wp1 and sweeps counter-clockwise by arcAngle degrees.

      Parameters:
      wpc - the center of the arc (not included in the output)
      wp1 - the first leg endpoint; the distance wpc→wp1 defines the radius
      arcAngle - the CCW sweep angle in degrees
      Returns:
      array of 60+ 1 world points tracing the arc from wp1

    • getEllipsePoints

      public static Point2D.Double[] getEllipsePoints(double w, double h, double azimuth, int numFill, Point2D.Double center)
      Build an array of world points approximating an ellipse.

      The ellipse is defined by its half-widths (w/2, h/2) and an azimuth rotation. Four primary compass points are computed first, the centroid is recomputed from those, and then 4 * numFill equally-spaced angular samples are generated. A closing point equal to the first is appended so the returned polygon is explicitly closed.

      Parameters:
      w - full width of the ellipse in world units
      h - full height of the ellipse in world units
      azimuth - rotation of the ellipse in degrees (azimuth convention: 0 = north, 90 = east)
      numFill - number of sample points per quadrant; the total returned is 4 * numFill + 1
      center - the center of the ellipse
      Returns:
      array of world points approximating the ellipse, closed at the last element

    • getMeanPixelDensity

      public static double getMeanPixelDensity(IContainer container)
      Estimate the pixel density of the container in pixels per world unit.

      Computed as the diagonal pixel length divided by the diagonal world length across the full component bounds. The bigger this number is, the more zoomed in the view is. Returns 0 if the component is too small to produce a meaningful estimate.

      Parameters:
      container - the container to measure; must not be null
      Returns:
      approximate pixels per world unit, or 0 if the component is too small

    • isPointNearPath

      public static boolean isPointNearPath(Path2D.Double path, Point2D.Double wp, double tolWorld)
      Test whether a world point lies within a given tolerance of any segment in a straight-segment Path2D.Double.

      Proximity to path vertices is also tested (a point exactly on a vertex counts as a hit). SEG_CLOSE is treated as a segment from the last point back to the most recent SEG_MOVETO point.

      Parameters:
      path - the world path to test; null returns false
      wp - the world point to test; null returns false
      tolWorld - tolerance distance in world units; must be ≥ 0
      Returns:
      true if wp is within tolWorld of any segment or vertex in path
      Throws:
      IllegalArgumentException - if the path contains curve segments

    • closestPointOnSegment

      public static Point2D.Double closestPointOnSegment(Point2D.Double p1, Point2D.Double p2, Point2D.Double wp)
      Return the point on segment a→b that is closest to p.

      If the segment is degenerate (zero length) the method returns a copy of a.

      Parameters:
      p1 - one end of the segment
      p2 - the other end of the segment
      wp - the query point
      Returns:
      the closest point on the segment