Skip to content

refactor: remove the shapely dependency - #339

Draft
ormsbee wants to merge 1 commit into
mainfrom
ormsbee/remove-shapely
Draft

ormsbee wants to merge 1 commit into
mainfrom
ormsbee/remove-shapely

Conversation

@ormsbee

@ormsbee ormsbee commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Description

ImageResponse (<imageresponse>, "Image Mapped Input") was the only code in this repo that used shapely. For each entry in an <imageinput>'s regions attribute, it built the convex hull of the points and checked whether the learner's click was strictly inside it.

This PR replaces that with is_inside_convex_hull() in capa/util.py and removes shapely from pyproject.toml and uv.lock. The new function is about 30 lines of standard-library Python: Andrew's monotone chain for the hull, then a cross-product test against each edge.

The arithmetic uses fractions.Fraction instead of floats. GEOS, the C++ library under shapely, uses extended-precision predicates, so it gives the right answer when a click is on an edge or within rounding distance of one. Plain float arithmetic does not: for the region [[0, 0], [1.1, 5.5], [0, 9]] and a click at [1, 5], shapely says inside and a float cross product says not inside. Fractions are exact, so the new code matches shapely there (test_is_inside_convex_hull_is_exact).

The regions of one <imageinput> can have at most 1,000 points between them (ImageResponse.max_region_points). More than that is an error. See Performance below for why.

numpy stays. It is a direct dependency, and responsetypes.py still imports it.

Compatibility

Grading of well-formed regions: no change

I compared the new function against shapely 2.2.0 (GEOS 3.14.1) on 740,009 random (region, click) pairs and got 0 differences. The mix was:

  • integer, half-integer, decimal, and arbitrary float coordinates
  • 0 to 10 points per region, with duplicates, collinear points, and z coordinates
  • clicks exactly on vertices and edges
  • 60,000 clicks placed on an edge whose endpoints are decimals that aren't exact as floats, so the answer depends on the last bit
  • 40,000 clicks on near-zero-area slivers

These existing behaviors are kept, and now have tests:

  • A click on a region's border is incorrect. (A click on a rectangle's border is correct. That inconsistency was already there.)
  • A region is the convex hull of its points, in whatever order they are listed. A concave outline is graded as its hull.
  • A region with no area (fewer than three distinct points, or all points on one line) never matches.
  • A third (z) coordinate is ignored, and numeric strings like "10" are accepted as coordinates.

What does change

  1. Exception types for malformed regions. These inputs raised before and still raise, but not always the same exception. Nothing in this repo catches shapely's exceptions. submit_problem re-raises anything that isn't one of the capa error types, before and after.

    regions contains Before After
    Infinity, or a float literal too big for a float, like 1e400 shapely.errors.GEOSException OverflowError
    NaN as only one of x or y shapely.errors.GEOSException ValueError
    a string or an object where an [x, y] point should be TypeError ValueError
    a list of points where a number should be ValueError TypeError
    a point with 1 or 4+ numbers, a non-numeric string, null, an integer too big for a float ValueError / TypeError / OverflowError same as before
  2. A [NaN, NaN] point is now an error. shapely treated it as an empty point. If it wasn't the first point, it was ignored and the rest of the region graded normally. If it was the first point, the whole region silently never matched. Now both raise ValueError. This needs a literal NaN in the regions attribute, so I doubt any real content has it, but it is an input that used to grade and now doesn't.

  3. A click coordinate with more than 308 digits used to raise OverflowError and is now graded as incorrect. The frontend can't produce this; it takes a hand-made request.

  4. More than 1,000 points in one regions attribute is now an error. The count is the total over all of the regions of one <imageinput>. Over the limit, grading a click on that input raises ValueError, wherever the click is, unless a rectangle on the same input already matched it. Before, it was graded. I don't know of real content anywhere near this size, but I have no data on it.

Performance

For a typical 4-point region, one check takes 0.016 ms, against 0.012 ms with shapely.

The new code falls behind as the number of points grows. For a single region with 1,000 points it is 4 to 8 times slower than shapely, and for 20,000 points it took 263 ms against 42 ms. That is why the total number of points in one regions attribute is limited to 1,000.

Time to grade one click that matches nothing, which is the worst case, with 1,000 points in total:

Regions this PR
1 region of 1,000 points, integer coordinates 9 ms
1 region of 1,000 points, float coordinates 17 ms
10 regions of 100 points, float coordinates 16 ms
250 regions of 4 points 4 ms

All of these were measured on one machine.

Downstream

  • Anything that got shapely only as a transitive dependency of xblocks-core will stop getting it.
  • openedx-platform lists Shapely in its own pyproject.toml with the comment "used for image click regions in capa". Nothing in its master imports shapely (checked at 46c8c9b4c8), so that entry can be removed once openedx-platform picks up a release that has this change.
  • shapely is not in openedx-platform's codejail sandbox requirements, so instructor-written grading code is not affected.

Notes for reviewers

  • Release. python-semantic-release won't cut a release for a refactor: commit on its own, so this will ship with the next fix: or feat:. openedx-platform can't drop Shapely until then.
  • uv.lock. Besides removing shapely, uv lock (0.13.7) rewrote the markers on the asgiref and sqlparse dependencies of the Django 5.2 entry. I didn't edit the lock by hand. The new markers select those two packages in the same cases as before, and uv sync --locked accepts the file.
  • Problems I noticed in ImageResponse and did not fix, since they are separate from this change:
    • A malformed rectangle attribute raises TypeError: list indices must be integers or slices, not str instead of the intended "Error in problem specification" message. The error path does self.ielements[aid], which indexes a list with the input's id.
    • regions="[[]]" raises IndexError at parsed_region[0][0].
    • The border inconsistency between rectangles and regions described above.

Testing

  • New unit tests for is_inside_convex_hull() in test_util.py: inside, outside, on an edge, on a vertex, point order, redundant points, fractional and negative coordinates, regions with no area, the exactness case above, and malformed points.
  • New end-to-end grading tests in ImageResponseTest for borders, point order, fractional coordinates, regions with no area, and the 1,000-point limit (for one region, and across many regions). I ran all but the limit tests against the shapely implementation before switching, and they passed there too.
  • tox passes for quality, docs, py312-django42, and py312-django52 (899 tests) from the new lock file. I confirmed that import shapely fails in those environments.
  • The comparison against shapely described under Compatibility. The script isn't part of this PR, since it needs shapely installed.

Manual testing (not yet done)

I have not run this in an LMS. To check it by hand:

  1. Add a problem with <imageresponse><imageinput src="..." width="400" height="400" regions="[[100,100], [300,100], [300,300], [100,300]]"/></imageresponse>.
  2. Click in the middle of the image and submit. It should be correct.
  3. Click outside the square and submit. It should be incorrect.

Merge checklist:
Check off if complete or not applicable:

  • Version bumped (N/A: the version comes from the release tag)
  • Changelog record added (N/A: this repo has no changelog)
  • Documentation updated (not only docstrings) (N/A)
  • Fixup commits are squashed away
  • Unit tests added/updated
  • Manual testing instructions provided
  • Noted any: Concerns, dependencies, migration issues, deadlines, tickets

🤖 Generated with Claude Code

@ormsbee
ormsbee force-pushed the ormsbee/remove-shapely branch from f749fdf to bb99bc8 Compare November 20, 2026 04:15
@ormsbee ormsbee changed the title build: remove the shapely dependency refactor: remove the shapely dependency Nov 20, 2026
ImageResponse was the only code that used shapely. It used it to check
whether a click is strictly inside the convex hull of a region's points.
That check is now is_inside_convex_hull() in capa/util.py, which only
needs the standard library.

The new check uses exact arithmetic, so it grades every well-formed
region the same way shapely did, including clicks that are on or right
next to an edge. Malformed regions are still an error, but some of the
exception types are different, and a [NaN, NaN] point is now an error
instead of being ignored.

The regions of one <imageinput> can now have at most 1000 points between
them, and more than that is an error. The new check is slower than
shapely when there are a lot of points. With the limit, grading a click
took at most about 17 ms when measured.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant