Skip to content

Chipping Services

geoembed.chipping.services

Domain services for chipping logic — shared between all backends.

StrideService

Shared domain logic for calculating chip overlaps.

Ensures chips cover the entire source image without gaps at the edges. Instead of padding (which adds fake data) or dropping edges (which loses data), this calculates the precise overlap so that the last chip aligns perfectly with the image edge.

calculate_optimal_overlap(image_dims, chip_dims) staticmethod

Calculate the minimal overlap required for full image coverage.

The algorithm determines the largest integer stride (step size) such that an integer number of steps exactly spans the remaining image dimension.

Formula: Overlap = Chip_Size - Stride

Parameters:

Name Type Description Default
image_dims tuple[int, int]

Dimensions of the source image (Width, Height).

 required
chip_dims tuple[int, int]

Dimensions of the desired chip (Width, Height).

 required

Returns:

Type Description
tuple[int, int]

Tuple of (overlap_x, overlap_y) in pixels.
Source code in src/geoembed/chipping/services.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
@staticmethod
def calculate_optimal_overlap(
    image_dims: tuple[int, int], chip_dims: tuple[int, int]
) -> tuple[int, int]:
    """
    Calculate the minimal overlap required for full image coverage.

    The algorithm determines the largest integer stride (step size) such that
    an integer number of steps exactly spans the remaining image dimension.

    Formula: Overlap = Chip_Size - Stride

    Args:
        image_dims: Dimensions of the source image (Width, Height).
        chip_dims: Dimensions of the desired chip (Width, Height).

    Returns:
        Tuple of (overlap_x, overlap_y) in pixels.
    """
    w, h = image_dims
    cw, ch = chip_dims

    def _get_stride(total_dim: int, chip_dim: int) -> int:
        target_start = total_dim - chip_dim
        if target_start <= 0:
            return 0

        steps = math.ceil(target_start / chip_dim)
        for i in range(steps, target_start + 1):
            stride = target_start / i
            if stride.is_integer():
                return chip_dim - int(stride)
        return chip_dim

    return _get_stride(w, cw), _get_stride(h, ch)