Add dash parameter for line, polygon, and rectangle drawing by Krishnachaitanyakc · Pull Request #9490 · python-pillow/Pillow

Krishnachaitanyakc · 2026-03-25T02:32:26Z

Summary

Adds a dash parameter to ImageDraw.line(), ImageDraw.polygon(), and ImageDraw.rectangle() that enables drawing dashed outlines, implemented in the Python layer.

The dash pattern follows the SVG stroke-dasharray specification: a tuple of ints specifying alternating drawn/blank segment lengths (e.g. (10, 5) draws 10px, skips 5px, repeats)
Odd-length patterns are automatically doubled per SVG spec
The dash pattern is continuous across connected line segments and polygon/rectangle edges
Empty dash tuples raise ValueError
Fill is drawn normally; only the outline/stroke is dashed
Fully backward compatible: all existing behavior is preserved when dash is not specified

Reference

This implementation follows the SVG stroke-dasharray specification:
https://www.w3.org/TR/SVG2/painting.html#StrokeDashing

Example usage

from PIL import Image, ImageDraw

im = Image.new("RGB", (200, 200), "white")
draw = ImageDraw.Draw(im)

# Dashed line
draw.line([(10, 100), (190, 100)], fill="black", width=2, dash=(10, 5))

# Dashed rectangle with fill
draw.rectangle([20, 20, 180, 60], fill="lightyellow", outline="blue", width=2, dash=(15, 5, 5, 5))

# Dashed polygon with fill
draw.polygon([(50, 120), (150, 120), (150, 180), (50, 180)], fill="lightblue", outline="red", width=2, dash=(10, 5))

Closes #9127

Test plan

Added 10 new tests covering dashed lines, polygons, and rectangles
Tests cover: basic dash, multi-segment lines, odd-length patterns, empty dash error, polygon with/without fill, rectangle with/without fill
All 281 existing test_imagedraw.py tests continue to pass (backward compatibility verified)
Reference images generated and included for pixel-exact assertions
Documentation updated for all three methods with versionadded:: 12.2.0

Add a `dash` parameter to `ImageDraw.line()`, `ImageDraw.polygon()`, and `ImageDraw.rectangle()` methods that allows drawing dashed outlines. The dash pattern follows the SVG `stroke-dasharray` specification: - Accepts a tuple of ints specifying alternating drawn/blank segment lengths - Odd-length patterns are automatically doubled per the SVG spec - The dash pattern is continuous across connected line segments and polygon edges - Empty dash tuples raise ValueError Closes python-pillow#9127

for more information, see https://pre-commit.ci

Pending pypa/build#1003

- Annotate pixels_used as float to fix float/int assignment mismatch - Rename redefined 'points' variable to 'joint_points' in curve joint code - Cast flat xy to Sequence[float] before slicing to fix type compatibility

for more information, see https://pre-commit.ci

radarhere · 2026-03-29T07:49:49Z

Could you link to the SVG specification that you used as a reference?

Krishnachaitanyakc · 2026-03-29T13:26:49Z

@radarhere updated the description

radarhere · 2026-03-30T10:48:29Z

Did you use AI to create this PR?

Krishnachaitanyakc · 2026-03-30T12:50:41Z

@radarhere I used AI to plan and implement yes, but did manually verify the changes and tested them

Assert that odd pattern image matches even pattern image

Krishnachaitanyakc · 2026-04-17T18:41:19Z

@radarhere can you please review this?

radarhere · 2026-04-17T23:26:45Z

This is on my list of things to look at. However, as I'm doing this in my spare time in an underpaid capacity, and trying to also address other issues and PRs, I may not get to it immediately.

radarhere · 2026-05-24T12:22:54Z

I've combined the different shape tests, checking the visual output for more operations.

However, when I changed the polygon points to be something other than a rectangle, I found that the dashed line does exactly sit on the edge of the polygon.

I can think of a solution to this when the width is 1 pixel, but more than that could be complicated. Would you be happy with only supporting widths of 1 pixel?

akx

In imagedraw_dash_polygon.png, the diagonal dashed line appears 1px inside the filled triangle. Why is that?

EDIT: ah, radarhere mentioned this just above.

akx · 2026-08-11T12:17:00Z

I think this could also be implemented in the C drawing code, where it's rather easy to just skip drawing some pixels that would otherwise be drawn, based on a pattern mask?

codspeed-hq · 2026-08-25T07:09:35Z

Merging this PR will degrade performance by 23.8%

⚠️

Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

❌ 4 regressed benchmarks
✅ 551 untouched benchmarks
⏩ 335 skipped benchmarks¹

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Benchmark	`BASE`	`HEAD`	Efficiency
❌	`test_draw_lines[1237x811-RGBA]`	243 µs	329.6 µs	-26.28%
❌	`test_draw_lines[1237x811-LA]`	242.9 µs	329.4 µs	-26.27%
❌	`test_draw_lines[1237x811-RGB]`	248.5 µs	335.7 µs	-25.97%
❌	`test_draw_lines[1237x811-L]`	405.1 µs	483.4 µs	-16.2%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

_{Comparing Krishnachaitanyakc:add-dashed-line-support (9341c21) with main (a9cbfbe)²}

335 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩
No successful run was found on main (807d689) during the generation of this report, so a9cbfbe was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

akx · 2026-08-25T07:07:10Z

+static inline int
+should_draw_dash(int i, PyObject *dash) {
+    if (dash == NULL) {
+        return 1;
+    }
+    int total = 0;
+    int tuple_index = -1;
+    int tuple_size = PyTuple_GET_SIZE(dash);
+    while (total <= i) {
+        tuple_index += 1;
+        if (tuple_index == tuple_size) {
+            tuple_index = 0;
+        }
+        PyObject *value = PyTuple_GetItem(dash, tuple_index);
+        if (!PyLong_Check(value)) {
+            return 0;
+        }
+        int v = PyLong_AsLongLong(value);
+        if (v == -1 && PyErr_Occurred()) {
+            return 0;
+        }
+        total += v;
+    }
+    return tuple_index % 2 == 0;
+}


Mmmm, I'd maybe not do Python object conversions for every dashed pixel to be drawn or not drawn, but instead convert the tuple into a C struct before passing to line*?

EDIT: it may also be a good idea to look at separate dashed variants of these functions, since a per-pixel check in the hot path is likely to degrade perf for all drawing operations for a somewhat niche feature.

EDIT 2: In fact, doesn't the dash array basically decompose into an array of on/off states + length, so accessing it to figure out whether to draw is then just [i % state_array_length]...

In fact, doesn't the dash array basically decompose into an array of on/off states + length, so accessing it to figure out whether to draw is then just [i % state_array_length]...

Isn't this complicated by the fact that the dash on/off states might have uneven lengths, under the API of this PR?

instead convert the tuple into a C struct before passing to line*?

You're suggesting allocating a struct that contains the length of the dash array, and the values within? Is that manifestly different from what the Python API is does under the hood?

a per-pixel check in the hot path

It shouldn't be per-pixel anymore, since 1af2a67

You're suggesting allocating a struct that contains the length of the dash array, and the values within? Is that manifestly different from what the Python API is does under the hood?

Yep, and I think it is. Right now each call to should_draw_dash involves, at a quick look, (not including the trivial operations like field retrievals that would need to be done with the struct too):

Type/subtype check (PyTuple_Check) in PyTuple_GET_SIZE

Type/subtype check (PyTuple_Check) in PyTuple_GetItem

Bounds check in PyTuple_GetItem

Type/subtype check PyLong_Check

Type/subtype check (PyLong_Check) in PyLong_AsLongLong

_PyLong_CompactValue or _PyLong_AsByteArray of the value

So it does sound like that's worth doing upfront, at least to something like

struct DashArray { size_t n_states; uint32_t states[]; }

in a single pre-pass. (I'm assuming we might not really need long long (64-bit) values for states?)

Isn't [[i % state_array_length]] complicated by the fact that the dash on/off states might have uneven lengths, under the API of this PR?

Just "exploding" the on-off states into chars, (at the expense of taking up sum(dash_array) bytes of memory plus a size_t for the length) is not complicated. (Could also pack 8 states down to a byte, so the expense is ceil(sum(dash_array) / 8), but the indexing becomes fiddlier.) That implementation of course means we'd probably need to bound the maximum length of the dash states, maybe to... 16K entries altogether? 🤷

But just converting the tuple to something like that DashArray above should be a lot more efficient, anyway, so might not be worth it to bother with exploding on top of that.

It shouldn't be per-pixel anymore, since 1af2a67

Ah yeah, checking for dashness at all before the loops is a good idea. Whether to draw the pixel or not has to be done for every pixel though, and that involves the above Python value operations right now.

akx · 2026-08-25T11:06:19Z

-        for (i = 0; i < dy; i++) {
-            point8(im, x0, y0, ink);
-            y0 += ys;
+        if (dash != NULL) {


It would probably be fine to always use the Bresenham algorithm when dashing and leave the fast paths (dx == 0, dy == 0) alone. Dashed line drawing will be slower anyhow due to the dash pattern check.

The GEN_LINE() stuff from #9772 would help there, I think - that could maybe be merged first? :)

Krishnachaitanyakc and others added 5 commits March 24, 2026 22:31

[pre-commit.ci] auto fixes from pre-commit.com hooks

51ca4e6

for more information, see https://pre-commit.ci

Skip build 1.4.1 for lint

ffd8dc2

Pending pypa/build#1003

Fix mypy type errors in ImageDraw.py

10f007c

- Annotate pixels_used as float to fix float/int assignment mismatch - Rename redefined 'points' variable to 'joint_points' in curve joint code - Cast flat xy to Sequence[float] before slicing to fix type compatibility

[pre-commit.ci] auto fixes from pre-commit.com hooks

eae92d6

for more information, see https://pre-commit.ci

radarhere reviewed Mar 25, 2026

View reviewed changes

Comment thread tox.ini Outdated

radarhere added 2 commits March 27, 2026 00:23

Merge branch 'main' into add-dashed-line-support

108ea06

Remove build upgrade

ae1c06b

radarhere added the 🤖-assisted AI-assisted label Mar 30, 2026

radarhere added 2 commits April 11, 2026 19:15

Updated version

44a04e4

Do not convert to float when normalizing

736d984

radarhere mentioned this pull request Apr 11, 2026

Assert that odd pattern image matches even pattern image Krishnachaitanyakc/Pillow#1

Merged

radarhere and others added 4 commits April 11, 2026 21:37

Simplified code

bbd1e59

Assert that odd pattern image matches even pattern image

86d79d0

Match error message

b079607

Merge pull request #1 from radarhere/add-dashed-line-support

52b6e3f

Assert that odd pattern image matches even pattern image

This was referenced May 2, 2026

Call C draw_lines directly from _draw_dashed_line Krishnachaitanyakc/Pillow#2

Merged

Combine tests to check output visually Krishnachaitanyakc/Pillow#3

Closed

radarhere and others added 5 commits May 13, 2026 09:58

Merge branch 'main' into add-dashed-line-support

d5dac21

Call C draw_lines directly from _draw_dashed_line

523ae52

Do not draw dashed line if width is zero or ink would be invisible

7ca3a90

Do not double the pattern length

b0cf48f

Combine tests to check output visually

ca4178e

radarhere mentioned this pull request Jun 6, 2026

Support for dashed lines? #9127

Open

akx reviewed Aug 11, 2026

View reviewed changes

Merge branch 'main' into add-dashed-line-support

91d987a

radarhere mentioned this pull request Aug 25, 2026

Add _normalize_coords() to reduce duplicate code #9899

Merged

akx reviewed Aug 25, 2026

View reviewed changes

Only apply dash for width 1

9341c21

radarhere force-pushed the add-dashed-line-support branch from 30c316d to 9341c21 Compare August 25, 2026 07:51

Move dash check outside for loop

1af2a67

akx reviewed Aug 25, 2026

View reviewed changes

Uh oh!

Uh oh!

Conversation

Krishnachaitanyakc commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Reference

Example usage

Test plan

Uh oh!

Uh oh!

radarhere commented Mar 29, 2026

Uh oh!

Krishnachaitanyakc commented Mar 29, 2026

Uh oh!

radarhere commented Mar 30, 2026

Uh oh!

Krishnachaitanyakc commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Krishnachaitanyakc commented Apr 17, 2026

Uh oh!

radarhere commented Apr 17, 2026

Uh oh!

radarhere commented May 24, 2026

Uh oh!

akx left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

akx commented Aug 11, 2026

Uh oh!

codspeed-hq Bot commented Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will degrade performance by 23.8%

Performance Changes

Footnotes

Uh oh!

akx Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

radarhere Aug 29, 2026

Choose a reason for hiding this comment

Uh oh!

akx Aug 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

akx Aug 25, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Krishnachaitanyakc commented Mar 25, 2026 •

edited

Loading

Krishnachaitanyakc commented Mar 30, 2026 •

edited

Loading

akx left a comment •

edited

Loading

codspeed-hq Bot commented Aug 25, 2026 •

edited

Loading

akx Aug 25, 2026 •

edited

Loading