A Practical Contract for Validating Portrait Crop Coordinates

A crop validator is a small example of a larger engineering problem: a review tool needs a precise contract before it can decide whether stored coordinates are usable. A rectangle that looks obvious in a UI becomes ambiguous when one component uses inclusive endpoints, another treats the lower-right corner as exclusive, and a third rotates the image before interpreting the same numbers. This article builds a small Python check for declared portrait crop metadata, then examines the boundaries that the function deliberately does not cover.

The sample data is synthetic. The function does not read images, identify people, infer consent, measure whether a face is recognizable, or call an external image-generation API. I work on AI Dating Photo Generator, a browser-based tool for exploring portrait options at dating app photo generator. This technical example is independent of that product's implementation and was prepared with AI assistance. Preparing a photoshoot is free; generating images uses paid credits. Check current pricing and privacy terms on the product site before using it.

Define the coordinate contract

Assume the input describes a two-dimensional image after the application has applied any orientation transformation. The origin is the upper-left corner. The x coordinate increases toward the right and the y coordinate increases toward the bottom. Width and height are positive integers measured in pixels, while left and top are nonnegative integer offsets from the origin.

Represent a crop with (left, top, crop_width, crop_height). The crop occupies the half-open interval [left, left + crop_width) on the x axis and [top, top + crop_height) on the y axis. A crop can end exactly at the right or bottom edge, but it cannot extend past either edge. Half-open intervals make the full image naturally expressible as (0, 0, width, height) and make its pixel count equal to crop_width * crop_height.

These choices are not universal. Some graphics libraries use inclusive coordinates, floating-point normalized values, or a center-and-radius representation. A boundary function should not silently reinterpret those alternatives. Convert explicitly at the boundary, document the conversion, and test it independently. The code below accepts only the contract described here.

A deliberately small validator

def check_crop(width, height, left, top, crop_width, crop_height):
    values = (width, height, left, top, crop_width, crop_height)
    if any(type(value) is not int for value in values):
        return False
    if width <= 0 or height <= 0 or left < 0 or top < 0:
        return False
    if crop_width <= 0 or crop_height <= 0:
        return False
    return left + crop_width <= width and top + crop_height <= height

The explicit type(value) is int rule rejects Boolean values. In Python, bool is a subclass of int, so isinstance(True, int) would otherwise pass. Rejecting booleans is a local policy for this example, not a statement that every API must use this policy. It prevents an accidental True from becoming a one-pixel width in a data pipeline.

The function returns a Boolean rather than an error message to keep the core example small. An application with a user-facing editor should normally report which field is invalid. It should distinguish an absent coordinate from a non-integer coordinate, a negative offset, an empty crop, and an out-of-bounds rectangle. These cases have different remedies: a user might fix a typo, change the selected image, or revise a crop after an orientation change.

Exercise the edges with synthetic cases

The following table is intentionally small. It covers the entire image, an edge-aligned crop, a one-pixel overflow, negative offsets, zero-size input, and a Boolean value. It is not a comprehensive test suite or evidence about a third-party image service. The examples run locally and contain no photographs or personal information.

cases = [
    ((800, 600, 0, 0, 800, 600), True),
    ((800, 600, 10, 20, 790, 580), True),
    ((800, 600, 10, 20, 791, 580), False),
    ((800, 600, -1, 0, 30, 30), False),
    ((800, 600, 0, 0, 0, 50), False),
    ((800, 600, True, 0, 30, 30), False),
]
for args, expected in cases:
    actual = check_crop(*args)
    assert actual is expected, (args, expected, actual)
print(f"{len(cases)} synthetic cases passed")

The second case ends at (800, 600) and is valid. Increasing its width by one moves the right edge to 801, outside the declared image. This pair catches a common off-by-one error while keeping all other inputs constant. Add a similar pair for the bottom edge, tests for tiny images, and very large numbers when preparing a production test suite.

Property-based tests can widen coverage. For any positive dimensions, the full-frame crop should be accepted. For any accepted crop, increasing its width beyond width - left should fail. An accepted crop also cannot have a negative offset or a zero dimension. These properties test relationships instead of memorizing a handful of example values, but they still validate the declared coordinate contract rather than the visual quality of a picture.

Orientation and provenance are separate inputs

A JPEG may carry an orientation flag that changes its displayed width and height. If one component stores raw file dimensions while another stores coordinates for the rotated display, both components can produce integers that look reasonable while referring to different pixels. Choose a canonical orientation, apply it before cropping, and record whether the dimensions refer to raw or normalized pixels.

Dimensions supplied by a browser, a metadata library, and a thumbnail service can also differ after resizing. Store which representation was measured and avoid applying a crop recorded for a large original directly to a thumbnail without an explicit transformation. A scale conversion may need rounding; define its rounding rule and test the resulting edge cases instead of assuming that multiplying by a ratio preserves every boundary.

Treat metadata as untrusted input even when it came from your own client. A web request can be incomplete, stale, or modified before it reaches a server. Validate at the point where the crop is consumed, and verify that its source image identifier and version still refer to the intended asset. This example does not provide an image identifier or version check; a real workflow must add one.

Keep the human review separate

Being geometrically valid does not mean that a crop is appropriate. The check cannot determine whether the resulting portrait is recognizable, whether another person appears in the background, or whether a dating app permits a particular edited image. Those judgments require human review and current platform rules. Do not present a successful Boolean as a privacy, consent, or identity assessment.

A reviewer can use the technical result as a gate before viewing the crop. For example, reject impossible coordinates, then show the actual result to the image owner with enough context to compare it against the source. Explain any generated or edited content honestly. A person may decide that an image is too old or too different even though the crop is valid. The system should allow that decision without treating it as a software error.

Minimize what is recorded. The synthetic tests above need only dimensions and coordinates. A production service should define retention, deletion, and access rules for photographs and any review notes. Avoid placing image bytes, biometric inferences, or sensitive personal details into ordinary application logs simply to debug a coordinate problem. Redacted identifiers and a short-lived diagnostic record are often more appropriate, subject to the application's actual privacy requirements.

Integration checklist

Before integrating this helper, write down the coordinate origin, units, orientation, and interval semantics. Confirm that dimensions describe the same image representation to which the crop will be applied. Reject malformed values at the service boundary, then test edge-aligned and out-of-range cases in the exact runtime used by the application.

Keep serialization explicit. If a client sends JSON, confirm that each number is an integer after decoding and that missing fields do not acquire misleading defaults. A database migration or API version change should not silently switch from half-open rectangles to inclusive endpoints. Include a version field when the data contract may evolve, and write tests for old records before changing their interpretation.

Finally, test the UI and image processing components separately from this validator. This small function can rule out a class of impossible rectangles, but it cannot prove that a rendered image is safe, accurate, or fit for a particular audience. Clear boundaries make the helper easier to use correctly and make the remaining human and system responsibilities visible.