What are a line's exact dimensions in JavaFX 2?

Question

I'm wondering about a line's exact width in JavaFX 2.1.

Creating a straight line starting at point (10;10) and ending at point (20;10) should have an expected width of 10px. When reading the line's width a value of 11px is returned. When starting the attached example and making a screenshot you'll see - at a higher zoom level - the line has a width of 12px and a height of 2px.

Using a LineBuilder does not make any difference. I event tried to apply a different StrokeType without success.

Creating a square with a side length of 10 returns the expected width of 10px.

1. Why does line.getBoundsInLocal().getWidth() return different values from those I see in the rendered result (screenshot)?
2. Why is there a difference concerning width when creating lines and polygons?

Example:

import javafx.application.Application;
import javafx.scene.Group;
import javafx.scene.Scene;
import javafx.scene.shape.Line;
import javafx.scene.shape.Polygon;
import javafx.stage.Stage;

public class ShapeWidthDemo extends Application {
    @Override
    public void start(Stage stage) throws Exception {
        Group root = new Group();

        int startX = 10;
        int startY = 10;
        int length = 10;

        Line line = new Line(startX, startY, startX + length, startY);
        System.out.println("line width: " + line.getBoundsInLocal().getWidth());
        //->line width: 11.0
        System.out.println("line height: " + line.getBoundsInLocal().getHeight());
        //->line height: 1.0
        root.getChildren().add(line);

        int startY2 = startY + 2;

        Polygon polygon = new Polygon(
            startX, startY2,
            startX + 10, startY2, 
            startX + 10, startY2 + 10, 
            startX, startY2 + 10);
        System.out.println("polygon width: " + polygon.getBoundsInLocal().getWidth());
        //->polygon width: 10.0
        System.out.println("polygon height: " + polygon.getBoundsInLocal().getHeight());
        //->polygon height: 10.0
        root.getChildren().add(polygon);

        stage.setScene(new Scene(root, 100, 100));
        stage.show();
    }

    public static void main(String[] args) {
        launch(args);
    }
}

Answer 1

1) The line's end points are controlled by StrokeLineCap.
So with default stroke width you can get the "desired" values by

line.setStrokeType(StrokeType.CENTERED);
line.setStrokeLineCap(StrokeLineCap.BUTT);

... that the line has a width of 12px and a height of 2px.

You can get these values if StrokeType.OUTSIDE AND NOT StrokeLineCap.BUTT are applied. However the height remains in 2px even changing the stroke attributes. That's strange..

2) Its because of the polygon's stroke value is NULL by default. By setting it like polygon.setStroke(Color.RED); the stroke will render.

Answer 2

Think of the line itself as having no surface area whatsoever, it is infinitely thin. The only dimensions for the line come from the stroke.

When the StrokeType is CENTERED and the StrokeLineCap is SQUARE (the default values), then the area taken by the the line comes from evenly applying half the stroke width around the line in all directions.

In your example, you are drawing a horizontal line with a stroke of 1 at an integer co-ordinate. The JavaFX co-ordinate system is such that integer corners map to the lines between pixels. When you display a horizontal line with integer co-ordinates, the line itself crosses half of the two vertical pixels on either side of the line and ends up as a gray shaded antialiased line rather than a black line shading only one vertical pixel. Additionally, the StrokeLineCap of SQUARE applied at the line ends means that the stroke extends beyond the end points of the line by half the stroke width. This ends up shading a quarter of each pixel in the two pairs of pixels on either side of the line ends.

By offsetting the co-ordinates of the line by half a pixel, the line can be drawn such that it shades a single row of vertical pixels as now the line is falling along the middle of each pixel and the line stroke is extending to the top and bottom edges of each pixel. Additionally, setting the line cap to butt rather than square means that the shaded area for the line will not extend beyond the ends of the line.

Here is some sample code to demonstrate this. In the sample, only the last line completely shades exactly 10 pixels and no more. It is also the only line which has a width of 10 and integer co-ordinates in it's bounding box.

import javafx.application.Application;
import javafx.scene.Group;
import javafx.scene.Scene;
import javafx.scene.shape.Line;
import javafx.scene.shape.StrokeLineCap;
import javafx.stage.Stage;

public class LineBounds extends Application {
  public static void main(String[] args) { launch(args); }
  @Override public void start(Stage stage) throws Exception {
    double startX = 10;
    double startY = 10;
    double length = 10;

    Line lineSpanningPixelsSquareEnd = new Line(startX, startY, startX + length, startY);
    System.out.println("lineSpanningPixels (square) bounding box: " + lineSpanningPixelsSquareEnd.getBoundsInLocal());

    startX = 10;
    startY = 20;
    length = 10;

    Line lineSpanningPixelsButtEnd = new Line(startX, startY, startX + length, startY);
    lineSpanningPixelsButtEnd.setStrokeLineCap(StrokeLineCap.BUTT);
    System.out.println("lineSpanningPixels (butt) bounding box:   " + lineSpanningPixelsButtEnd.getBoundsInLocal());

    startX = 10;
    startY = 29.5;
    length = 10;

    Line lineOnPixelsSquareEnd = new Line(startX, startY, startX + length, startY);
    System.out.println("lineOnPixels (square) bounding box:       " + lineOnPixelsSquareEnd.getBoundsInLocal());

    startX = 10;
    startY = 39.5;
    length = 10;

    Line lineOnPixelsButtEnd = new Line(startX, startY, startX + length, startY);
    lineOnPixelsButtEnd.setStrokeLineCap(StrokeLineCap.BUTT);
    System.out.println("lineOnPixels (butt) bounding box:         " + lineOnPixelsButtEnd.getBoundsInLocal());

    stage.setScene(
      new Scene(
        new Group(
          lineSpanningPixelsSquareEnd, lineSpanningPixelsButtEnd, lineOnPixelsSquareEnd, lineOnPixelsButtEnd
        ), 100, 100
      )
    );
    stage.show();
  }
}

Output of the sample program is:

lineSpanningPixels (square) bounding box: BoundingBox [minX:9.5, minY:9.5, minZ:0.0, width:11.0, height:1.0, depth:0.0, maxX:20.5, maxY:10.5, maxZ:0.0]
lineSpanningPixels (butt) bounding box:   BoundingBox [minX:10.0, minY:19.5, minZ:0.0, width:10.0, height:1.0, depth:0.0, maxX:20.0, maxY:20.5, maxZ:0.0]
lineOnPixels (square) bounding box:       BoundingBox [minX:9.5, minY:29.0, minZ:0.0, width:11.0, height:1.0, depth:0.0, maxX:20.5, maxY:30.0, maxZ:0.0]
lineOnPixels (butt) bounding box:         BoundingBox [minX:10.0, minY:39.0, minZ:0.0, width:10.0, height:1.0, depth:0.0, maxX:20.0, maxY:40.0, maxZ:0.0]