diff --git a/Tests/images/imagedraw_regular_polygon__octagon_with_0_degree_rotation.png b/Tests/images/imagedraw_regular_polygon__octagon_with_0_degree_rotation.png new file mode 100644 index 000000000..6e529a1a4 Binary files /dev/null and b/Tests/images/imagedraw_regular_polygon__octagon_with_0_degree_rotation.png differ diff --git a/Tests/images/imagedraw_regular_polygon__square_with_0_degree_rotation.png b/Tests/images/imagedraw_regular_polygon__square_with_0_degree_rotation.png new file mode 100644 index 000000000..0c94dd42e Binary files /dev/null and b/Tests/images/imagedraw_regular_polygon__square_with_0_degree_rotation.png differ diff --git a/Tests/images/imagedraw_regular_polygon__square_with_45_degree_rotation.png b/Tests/images/imagedraw_regular_polygon__square_with_45_degree_rotation.png new file mode 100644 index 000000000..aef8dba52 Binary files /dev/null and b/Tests/images/imagedraw_regular_polygon__square_with_45_degree_rotation.png differ diff --git a/Tests/test_imagedraw.py b/Tests/test_imagedraw.py index 224914b94..b25fa3f6f 100644 --- a/Tests/test_imagedraw.py +++ b/Tests/test_imagedraw.py @@ -1092,3 +1092,101 @@ def test_same_color_outline(): operation, mode ) assert_image_similar_tofile(im, expected, 1) + + +@pytest.mark.parametrize( + "nb_polygon_sides, rotation, polygon_name", + [(4, 0, "square"), (8, 0, "octagon"), (4, 45, "square")], +) +def test_draw_regular_polygon(nb_polygon_sides, rotation, polygon_name): + im = Image.new("RGBA", size=(W, H), color=(255, 0, 0, 0)) + filename = ( + f"Tests/images/imagedraw_regular_polygon__{polygon_name}" + f"_with_{rotation}_degree_rotation.png" + ) + draw = ImageDraw.Draw(im) + draw.regular_polygon( + b_box=[(0, 0), (W, H)], nb_sides=nb_polygon_sides, rotation=rotation, fill="red" + ) + assert_image_equal(im, Image.open(filename)) + + +@pytest.mark.parametrize( + "nb_polygon_sides, expected_vertices", + [ + (3, [(6.7, 75.0), (93.3, 75.0), (50.0, 0.0)]), + (4, [(14.64, 85.36), (85.36, 85.36), (85.36, 14.64), (14.64, 14.64)]), + ( + 5, + [ + (20.61, 90.45), + (79.39, 90.45), + (97.55, 34.55), + (50.0, 0.0), + (2.45, 34.55), + ], + ), + ( + 6, + [ + (25.0, 93.3), + (75.0, 93.3), + (100.0, 50.0), + (75.0, 6.7), + (25.0, 6.7), + (0.0, 50.0), + ], + ), + ], +) +def test_compute_regular_polygon_vertices(nb_polygon_sides, expected_vertices): + vertices = ImageDraw._compute_regular_polygon_vertices( + nb_sides=nb_polygon_sides, b_box=[(0, 0), (100, 100)], rotation=0 + ) + assert vertices == expected_vertices + + +@pytest.mark.parametrize( + "nb_polygon_sides, bounding_box, rotation, expected_error, error_message", + [ + (None, [(0, 0), (100, 100)], 0, TypeError, "nb_sides should be an int"), + (1, [(0, 0), (100, 100)], 0, ValueError, "nb_sides should be an int > 2"), + (3, 100, 0, TypeError, "b_box should be a list/tuple"), + ( + 3, + [(0, 0), (50, 50), (100, 100)], + 0, + ValueError, + "b_box should have 2 items (top-left & bottom-right coordinates)", + ), + ( + 3, + [(50, 50), (0, None)], + 0, + ValueError, + "b_box should only contain numeric data", + ), + ( + 3, + [(50, 50), (0, 0)], + 0, + ValueError, + "b_box: Bottom-right coordinate should be larger than top-left coordinate", + ), + ( + 3, + [(0, 0), (100, 100)], + "0", + ValueError, + "rotation should be an int or float", + ), + ], +) +def test_compute_regular_polygon_vertices_input_error_handling( + nb_polygon_sides, bounding_box, rotation, expected_error, error_message +): + with pytest.raises(expected_error) as e: + ImageDraw._compute_regular_polygon_vertices( + nb_sides=nb_polygon_sides, b_box=bounding_box, rotation=rotation + ) + assert str(e.value) == error_message diff --git a/docs/reference/ImageDraw.rst b/docs/reference/ImageDraw.rst index 3faa0d3e0..8690b4de9 100644 --- a/docs/reference/ImageDraw.rst +++ b/docs/reference/ImageDraw.rst @@ -254,6 +254,22 @@ Methods :param outline: Color to use for the outline. :param fill: Color to use for the fill. + +.. py:method:: ImageDraw.regular_polygon(*, b_box, nb_sides, rotation=0, fill=None, outline=None) + + Draws a regular polygon inscribed in ``b_box``, + with ``nb_sides``, and rotation of ``rotation`` degrees + + :param b_box: A bounding box which inscribes the polygon + (e.g. b_box = [(50, 50), (150, 150)]) + :param nb_sides: Number of sides + (e.g. nb_sides=3 for a triangle, 6 for a hexagon, etc..) + :param rotation: Apply an arbitrary rotation to the polygon + (e.g. rotation=90, applies a 90 degree rotation) + :param outline: Color to use for the outline. + :param fill: Color to use for the fill. + + .. py:method:: ImageDraw.rectangle(xy, fill=None, outline=None, width=1) Draws a rectangle. diff --git a/src/PIL/ImageDraw.py b/src/PIL/ImageDraw.py index 33cb67923..b21cade7d 100644 --- a/src/PIL/ImageDraw.py +++ b/src/PIL/ImageDraw.py @@ -242,6 +242,13 @@ class ImageDraw: if ink is not None and ink != fill: self.draw.draw_polygon(xy, ink, 0) + def regular_polygon(self, *, nb_sides, b_box, rotation=0, fill=None, outline=None): + """Draw a regular polygon.""" + xy = _compute_regular_polygon_vertices( + nb_sides=nb_sides, b_box=b_box, rotation=rotation + ) + self.polygon(xy, fill=fill, outline=outline) + def rectangle(self, xy, fill=None, outline=None, width=1): """Draw a rectangle.""" ink, fill = self._getink(outline, fill) @@ -555,6 +562,136 @@ def floodfill(image, xy, value, border=None, thresh=0): edge = new_edge +def _compute_regular_polygon_vertices(*, nb_sides, b_box, rotation): + """ + Generate a list of vertices for a 2D regular polygon. + + :param nb_sides: Number of sides + (e.g. nb_sides = 3 for a triangle, 6 for a hexagon, etc..) + :param b_box: A bounding box which inscribes the polygon + (e.g. b_box = [(50, 50), (150, 150)]) + :param rotation: Apply an arbitrary rotation to the polygon + (e.g. rotation=90, applies a 90 degree rotation) + :return: List of regular polygon vertices + (e.g. [(25, 50), (50, 50), (50, 25), (25, 25)]) + + How are the vertices computed? + 1. Compute the following variables + - theta: Angle between the apothem & the nearest polygon vertex + - side_length: Length of each polygon edge + - centroid: Center of bounding box + - polygon_radius: Distance between centroid and each polygon vertex + - angles: Location of each polygon vertex in polar grid + (e.g. A square with 0 degree rotation => [225.0, 315.0, 45.0, 135.0]) + + 2. For each angle in angles, get the polygon vertex at that angle + The vertex is computed using the equation below. + X= xcos(φ) + ysin(φ) + Y= −xsin(φ) + ycos(φ) + + Note: + φ = angle in degrees + x = 0 + y = polygon_radius + + The formula above assumes rotation around the origin. + In our case, we are rotating around the centroid. + To account for this, we use the formula below + X = xcos(φ) + ysin(φ) + centroid_x + Y = −xsin(φ) + ycos(φ) + centroid_y + """ + # 1. Error Handling + # 1.1 Check `nb_sides` has an appropriate value + if not isinstance(nb_sides, int): + raise TypeError("nb_sides should be an int") + if nb_sides < 3: + raise ValueError("nb_sides should be an int > 2") + + # 1.2 Check `b_box` has an appropriate value + if not isinstance(b_box, (list, tuple)): + raise TypeError("b_box should be a list/tuple") + if not len(b_box) == 2: + raise ValueError( + "b_box should have 2 items (top-left & bottom-right coordinates)" + ) + + b_box_pts = [pt for corner in b_box for pt in corner] + if not all(isinstance(i, (int, float)) for i in b_box_pts): + raise ValueError("b_box should only contain numeric data") + + if b_box[1][1] <= b_box[0][1] or b_box[1][0] <= b_box[0][0]: + raise ValueError( + "b_box: Bottom-right coordinate should be larger than top-left coordinate" + ) + + # 1.3 Check `rotation` has an appropriate value + if not isinstance(rotation, (int, float)): + raise ValueError("rotation should be an int or float") + + # 2. Define Helper Functions + def _get_centroid(*, b_box): + return (b_box[1][0] + b_box[0][0]) * 0.5, (b_box[1][1] + b_box[0][1]) * 0.5 + + def _apply_rotation(*, point, degrees, centroid): + return ( + round( + point[0] * math.cos(math.radians(360 - degrees)) + - point[1] * math.sin(math.radians(360 - degrees)) + + centroid[0], + 2, + ), + round( + point[1] * math.cos(math.radians(360 - degrees)) + + point[0] * math.sin(math.radians(360 - degrees)) + + centroid[1], + 2, + ), + ) + + def _get_theta(*, nb_sides): + return 0.5 * (360 / nb_sides) + + def _get_polygon_radius(*, side_length, theta): + return (0.5 * side_length) / math.sin(math.radians(theta)) + + def _compute_polygon_vertex(*, angle, centroid, polygon_radius): + start_point = [polygon_radius, 0] + return _apply_rotation(point=start_point, degrees=angle, centroid=centroid) + + def _get_side_length(*, b_box, theta): + h = b_box[1][1] - b_box[0][1] + return h * math.sin(math.radians(theta)) + + def _get_angles(*, nb_sides, rotation): + angles = [] + degrees = 360 / nb_sides + # Start with the bottom left polygon vertex + current_angle = (270 - 0.5 * degrees) + rotation + for _ in range(0, nb_sides): + angles.append(current_angle) + current_angle += degrees + if current_angle > 360: + current_angle -= 360 + return angles + + # 3. Variable Declarations + vertices = [] + theta = _get_theta(nb_sides=nb_sides) + side_length = _get_side_length(theta=theta, b_box=b_box) + centroid = _get_centroid(b_box=b_box) + polygon_radius = _get_polygon_radius(side_length=side_length, theta=theta) + angles = _get_angles(nb_sides=nb_sides, rotation=rotation) + + # 4. Compute Vertices + for angle in angles: + vertices.append( + _compute_polygon_vertex( + centroid=centroid, angle=angle, polygon_radius=polygon_radius + ) + ) + return vertices + + def _color_diff(color1, color2): """ Uses 1-norm distance to calculate difference between two values.