lib.layout

  1import drawBot
  2import random
  3from typing import TypeAlias, Literal
  4from loguru import logger
  5from icecream import ic
  6
  7from lib import helpers
  8
  9UnitType: TypeAlias = Literal["mm", "pt"]
 10"""Unit type for measurement, either millimeters ('mm') or points ('pt')."""
 11
 12UnitMode: TypeAlias = Literal["mm", "pt", "relative"]
 13"""Mode for interpreting units: millimeters, points, or relative (percentage-based)."""
 14
 15BoxEdge: TypeAlias = Literal["top", "right", "bottom", "left"]
 16"""Represents the four edges of a box."""
 17
 18PageSize: TypeAlias = None | str | tuple[int, int]
 19"""Acceptable page size formats:
 20
 21- `None`
 22    - Default to current page size
 23- `str`
 24    - Page size name (e.g. `A4`, `Letter`, etc.)
 25    - See https://www.drawbot.com/content/canvas/pages.html#size for available sizes
 26- `tuple`
 27    - explicit `(width, height)` in points
 28"""
 29
 30
 31def pageIsEven() -> bool:
 32    """Returns True if the current page count is even, otherwise False."""
 33    return True if drawBot.pageCount() % 2 == 0 else False
 34
 35
 36def mm(number: int) -> float:
 37    """Convert millimeters to points.
 38
 39    Args:
 40        number: Value in millimeters.
 41
 42    Returns:
 43        Value converted to points.
 44    """
 45    mmToInch = 25.4 / 72
 46    return number / mmToInch
 47
 48
 49def cm(number: int) -> float:
 50    """Convert centimeters to points.
 51
 52    Args:
 53        number: Value in centimeters.
 54
 55    Returns:
 56        Value converted to points.
 57    """
 58    return mm(number * 10)
 59
 60
 61def pt(number: int, rounded=False) -> float:
 62    """Convert points to millimeters.
 63
 64    Args:
 65        number: Value in points.
 66        rounded: If True, round the result.
 67
 68    Returns:
 69        Value converted to millimeters.
 70    """
 71    mmToInch = 25.4 / 72
 72    value = mmToInch * number
 73    return round(value) if rounded else value
 74
 75
 76def getPageCoords() -> tuple[int]:
 77    """Returns current page `x, y, w, h`."""
 78    return 0, 0, drawBot.width(), drawBot.height()
 79
 80
 81def parsePageSize(value: PageSize) -> tuple[int, int]:
 82    """Parse `PageSize` into a tuple.
 83
 84    Args:
 85        value: Page size in one of the accepted formats.
 86
 87    Returns:
 88        Tuple of (width, height) in points.
 89    """
 90    if value == None:
 91        pageW, pageH = drawBot.width(), drawBot.height()
 92        logger.trace(
 93            f"Defaulting to {pt(pageW, rounded=True)}×{pt(pageH, rounded=True)}mm"
 94        )
 95        return pageW, pageH
 96    elif isinstance(value, str):
 97        try:
 98            return drawBot.sizes(value)
 99        except:
100            raise ValueError(
101                f"Invalid page size: {value}. Use a tuple or a valid page size string."
102            )
103    else:
104        return value
105
106
107def normalize(value: tuple) -> tuple:
108    """
109    Normalize tuple of `n` to 4 and parse `pageSize (str)`.
110
111    Args:
112        value: Tuple or page size string.
113
114    Returns:
115        Tuple of (x, y, w, h).
116    """
117    value = parsePageSize(value)
118
119    if isinstance(value, tuple) and len(value) == 4:
120        x, y, w, h = value
121    else:
122        x, y, w, h = 0, 0, *value
123
124    return x, y, w, h
125
126
127def mirror(values: tuple) -> tuple:
128    """Flip values horizontally.
129
130    Args:
131        values: Tuple of values to mirror.
132
133    Returns:
134        Mirrored tuple.
135    """
136    values = helpers.coerceList(values)
137
138    if len(values) == 4:
139        top, outer, bottom, inner = values
140        return top, inner, bottom, outer
141    elif len(values) == 2:
142        outer, inner = values
143        return inner, outer
144    else:
145        return values
146
147
148def toDimensions(value: tuple) -> tuple[int, int]:
149    """Returns `w, h`."""
150    _, _, w, h = normalize(value)
151    return w, h
152
153
154def toWidth(value: tuple | str) -> int:
155    """
156    Returns width from coords tuple or text string.
157
158    Args:
159        value: Coords tuple or text string.
160    """
161    if isinstance(value, str):
162        return drawBot.textSize(value)[0]
163    # Assume it’s already in correct format if number
164    elif isinstance(value, (int, float)):
165        return value
166    else:
167        w, _ = toDimensions(value)
168        return w
169
170
171def toHeight(value: tuple | str) -> int:
172    """
173    Returns height from coords tuple or text string.
174
175    Args:
176        value: Coords tuple or text string.
177    """
178    if isinstance(value, str):
179        return drawBot.textSize(value)[1]
180    # Assume it’s already in correct format if number
181    elif isinstance(value, (int, float)):
182        return value
183    else:
184        _, h = toDimensions(value)
185        return h
186
187
188def toPosition(value: tuple) -> tuple[int, int]:
189    """Returns `x, y`."""
190    x, y, _, _ = normalize(value)
191    return x, y
192
193
194def toCoords(value: tuple) -> tuple[int, int, int, int]:
195    """Returns `x, y, w, h`."""
196    return normalize(value)
197
198
199def toCenter(value: tuple) -> tuple[int, int]:
200    """Returns `x, y` center points."""
201    x, y, w, h = toCoords(value)
202    return x + w / 2, y + h / 2
203
204
205def unpackTwo(values, separator=" ", unit: UnitType = "mm"):
206    """Unpack two values, optionally converting to points.
207
208    Args:
209        values: Values to unpack.
210        separator: Separator for string input.
211        unit: Unit type for conversion.
212
213    Returns:
214        Tuple of two values, possibly converted to points.
215    """
216    # List coercion
217    values = helpers.coerceNumericList(values, separator)
218
219    # Manipulate tuple
220    if len(values) == 2:
221        x, y = values
222    else:
223        for side in values:
224            x = y = side
225
226    if unit == "mm":
227        return map(mm, [x, y])
228    else:
229        return x, y
230
231
232def unpackFour(values, separator=" ", unit: UnitType = "mm"):
233    """Unpack four values, optionally converting to points.
234
235    Args:
236        values: Values to unpack.
237        separator: Separator for string input.
238        unit: Unit type for conversion.
239
240    Returns:
241        Tuple of four values, possibly converted to points.
242    """
243    # List coercion
244    values = helpers.coerceNumericList(values, separator)
245
246    # Manipulate tuple
247    if len(values) == 4:
248        top, right, bottom, left = values
249    elif len(values) == 3:
250        top, right, bottom = values
251        left = right
252    elif len(values) == 2:
253        y, x = values
254        top = bottom = y
255        left = right = x
256    else:
257        for side in values:
258            top = right = bottom = left = side
259
260    if unit == "mm":
261        return map(mm, [top, right, bottom, left])
262    else:
263        return top, right, bottom, left
264
265
266def move(shape: tuple, x=0, y=0, mode: UnitMode = "mm"):
267    """
268    Move a shape by x and y offsets.
269
270    Args:
271        shape: Shape tuple (x, y, w, h).
272        x: Horizontal offset.
273        y: Vertical offset.
274        mode: `relative` to move by percentage of size
275
276    Returns:
277        Moved shape as (x, y, w, h).
278    """
279    shapeX, shapeY, shapeW, shapeH = shape
280
281    if mode == "relative":
282        x, y = x * shapeW, -y * shapeH
283    elif mode == "mm":
284        x, y = map(mm, [x, y])
285
286    return shapeX + x, shapeY - y, shapeW, shapeH
287
288
289def grow(
290    frame: tuple,
291    margin: tuple,
292    mode: UnitMode = "mm",
293    debug=False,
294):
295    """Grow in clock-wise manner.
296
297    Args:
298        frame: Frame tuple.
299        margin: Margin values.
300        mode: Unit mode.
301        debug: If True, draw debug overlay.
302
303    Returns:
304        Grown frame as (x, y, w, h).
305    """
306    frameX, frameY, frameW, frameH = toCoords(frame)
307    margin = unpackFour(margin, unit=mode)
308
309    if mode == "relative":
310        frameSize = (frameW, frameH) * 2
311        margin = [f * m for f, m in zip(frameSize, margin)]
312
313    mTop, mRight, mBottom, mLeft = margin
314    x, y = frameX - mLeft, frameY - mBottom
315    w, h = frameW + (mLeft + mRight), frameH + (mTop + mBottom)
316
317    coords = x, y, w, h
318
319    if debug:
320        xray(coords)
321
322    return coords
323
324
325def shrink(
326    frame: tuple,
327    margin: tuple,
328    mode: UnitMode = "mm",
329    debug=False,
330):
331    """Shrink in clock-wise manner.
332
333    Args:
334        frame: Frame tuple.
335        margin: Margin values.
336        mode: Unit mode.
337        debug: If True, draw debug overlay.
338
339    Returns:
340        Shrunk frame as (x, y, w, h).
341    """
342    # Inverse margin
343    margin = helpers.inverseValues(margin)
344    return grow(frame, margin, mode, debug)
345
346
347def shrinkWidth(
348    frame: tuple,
349    amount: int = 0.1,
350    origin: Literal["left", "right"] = "left",
351    mode: UnitMode = "relative",
352):
353    """Shorthand to decrease width.
354
355    Args:
356        frame: Frame tuple.
357        amount: Amount to shrink.
358        origin: Side to shrink from ('left' or 'right').
359        mode: Unit mode.
360
361    Returns:
362        Frame with reduced width.
363    """
364    if mode == "relative":
365        amount *= 2  # grow() modifies one side by default
366
367    margin = (0, amount, 0, 0) if origin == "left" else (0, 0, 0, amount)
368    return shrink(frame, margin=margin, mode=mode)
369
370
371def shrinkHeight(
372    frame: tuple,
373    amount: int = 0.1,
374    origin: Literal["top", "bottom"] = "top",
375    mode: UnitMode = "relative",
376):
377    """Shorthand to decrease height.
378
379    Args:
380        frame: Frame tuple.
381        amount: Amount to shrink.
382        origin: Side to shrink from ('top' or 'bottom').
383        mode: Unit mode.
384
385    Returns:
386        Frame with reduced height.
387    """
388    if mode == "relative":
389        amount *= 2  # grow() modifies one side by default
390
391    margin = (amount, 0, 0) if origin == "bottom" else (0, 0, amount)
392    return shrink(frame, margin=margin, mode=mode)
393
394
395LayoutDirection = Literal["columns", "rows"]
396
397
398def splitRelative(
399    coords: tuple,
400    formula="3/1",
401    gap=5,
402    mode: LayoutDirection = "columns",
403    unit: UnitType = "mm",
404    debug=False,
405) -> list[int]:
406    """
407    Split area by specified ratio.
408
409    Args:
410        coords: Container coordinates.
411        formula: Ratio formula (e.g. '3/1').
412        gap: Gap between splits.
413        mode: Split direction ('columns' or 'rows').
414        unit: Unit type for gap.
415        debug: If True, draw debug overlay.
416
417    Returns:
418        List of split rectangles as (x, y, w, h).
419
420    Example:
421        `3/1` => `75% 25%`
422    """
423    items = [float(item) for item in formula.split("/")]
424    length = len(items)
425    count = sum(items)
426
427    if unit == "mm":
428        gap = mm(gap)
429
430    gapCount = length - 1
431
432    containerX, containerY, containerW, containerH = coords
433
434    if mode == "rows":
435        dimension = containerH
436        itemW = containerW
437    else:
438        dimension = containerW
439        itemH = containerH
440
441    available = dimension - (gap * gapCount)
442    unit = available / count
443
444    result = []
445    x, y = containerX, containerY + containerH
446
447    for item in items:
448        itemDimension = item * unit
449
450        if mode == "rows":
451            itemH = itemDimension
452        else:
453            itemW = itemDimension
454
455        coords = x, y - itemH, itemW, itemH
456        result.append(coords)
457
458        if mode == "rows":
459            y -= itemH + gap
460        else:
461            x += itemW + gap
462
463    if debug:
464        xray(result)
465
466    return result
467
468
469# TODO: Deprecate alias
470# TODO: Rename mode to split
471split = splitRelative
472
473
474SplitMode = Literal["horizontal", "vertical"]
475
476Coordinates = tuple[float, float, float, float]
477
478
479def splitAbsolute(
480    container: Coordinates, split: SplitMode, size: float, gap: float
481) -> tuple[Coordinates, Coordinates]:
482    """
483    Splits a container into two rectangles along the specified mode, with a gap in between.
484
485    Args:
486        container (tuple): (x, y, w, h) of the container.
487        split (str): 'horizontal' or 'vertical'.
488        size (float): Size in mm of the new rectangle along the split axis.
489        gap (float): Gap in mm between the rectangles.
490
491    Returns:
492        tuple: (new_rect, remainder_rect)
493    """
494    x, y, w, h = container
495    size = mm(size)
496    gap = mm(gap)
497
498    if split == "horizontal":
499        new_rect = (x, y, size, h)
500        remainder_rect = (x + size + gap, y, w - size - gap, h)
501    elif split == "vertical":
502        new_rect = (x, y, w, size)
503        remainder_rect = (x, y + size + gap, w, h - size - gap)
504    else:
505        raise ValueError("mode must be 'horizontal' or 'vertical'")
506    return new_rect, remainder_rect
507
508
509def makeGrid(
510    frame: tuple,
511    rows=1,
512    cols=1,
513    gutter=5,
514    unit: UnitType = "mm",
515    debug=False,
516) -> list[tuple]:
517    """Create a grid of cells within a frame.
518
519    Args:
520        frame: Frame tuple.
521        rows: Number of rows.
522        cols: Number of columns.
523        gutter: Gutter size between cells.
524        unit: Unit type for gutter.
525        debug: If True, draw debug overlay.
526
527    Returns:
528        List of cell rectangles as (x, y, w, h).
529    """
530    frameX, frameY, frameW, frameH = frame
531    gutterX, gutterY = unpackTwo(gutter, unit=unit)
532    cells = []
533
534    # Cell width, height
535    w = (frameW - gutterX * (cols - 1)) / cols
536    h = (frameH - gutterY * (rows - 1)) / rows
537
538    for row in range(rows):
539        offsetY = (h + gutterY) * row
540        y = frameY + (frameH - h) - offsetY
541
542        for col in range(cols):
543            offsetX = (w + gutterX) * col
544            x = frameX + offsetX
545
546            coords = (x, y, w, h)
547            cells.append(coords)
548
549            if debug:
550                xray(coords)
551
552    return cells
553
554
555AlignX: TypeAlias = Literal["left", "center", "right", "stretch", None]
556"""Horizontal alignment options."""
557
558AlignY: TypeAlias = Literal["top", "center", "bottom", "stretch", None]
559"""Vertical alignment options."""
560
561AlignMode: TypeAlias = Literal["precise", "visual"]
562"""Alignment calculation mode: 'precise' for mathematical, 'visual' for optical centering."""
563
564
565def align(
566    parent: tuple,
567    child: tuple,
568    position: tuple[AlignX, AlignY] = ("center", "center"),
569    clip=True,
570    debug=False,
571    output: Literal["position", "coords"] = "coords",
572    mode: AlignMode = "precise",
573) -> tuple:
574    """
575    Align a child element within a parent rectangle.
576
577    Args:
578        parent: Parent rectangle (x, y, w, h).
579        child: Child rectangle or text.
580        position: Tuple of horizontal and vertical alignment.
581        clip: If True, clip child to parent size.
582        debug: If True, draw debug overlay.
583        output: Return type, either 'position' (tuple of 2) or 'coords' (tuple of 4).
584        mode: Alignment mode
585            - `precise`: Align mathematically
586            - `visual`: Nudge up if `AlignY=center`
587
588    Returns:
589        Aligned `position` or `coords` (based on output).
590    """
591    positionX, positionY = position
592    parentX, parentY, parentW, parentH = parent
593
594    childX, childY = toPosition(child)
595    childW, childH = toDimensions(child)
596
597    # Dimensions
598    if positionX in ["stretch", 3]:
599        w = parentW
600    elif clip:
601        w = min(parentW, childW)
602    else:
603        w = childW
604
605    if positionY in ["stretch", 3]:
606        h = parentH
607    elif clip:
608        h = min(parentH, childH)
609    else:
610        h = childH
611
612    difW, difH = parentW - w, parentH - h
613
614    # Position
615    if positionX in ["left", 0, "stretch", 3]:
616        x = parentX
617    elif positionX in ["right", 2]:
618        x = parentX + difW
619    elif positionX in ["center", 1]:
620        x = parentX + difW / 2
621    else:
622        # None = Leave as is
623        x = childX
624
625    if positionY in ["top", 0]:
626        y = parentY + difH
627    elif positionY in ["bottom", 2, "stretch", 3]:
628        y = parentY
629    elif positionY in ["center", 1]:
630        y = parentY + difH / 2
631    else:
632        # None = Leave as is
633        y = childY
634
635    if positionY == "center" and mode == "visual":
636        y += difH * 0.05  # Nudge up for visual centering
637
638    coords = x, y, w, h
639
640    if debug:
641        xray(coords)
642
643    return coords if output == "coords" else toPosition(coords)
644
645
646def canFitInside(parent: tuple, child: tuple) -> bool:
647    """Returns True if the child fits inside the parent dimensions."""
648    parentW, parentH = parent if len(parent) == 2 else toDimensions(parent)
649    childW, childH = child if len(child) == 2 else toDimensions(child)
650    return childW <= parentW and childH <= parentH
651
652
653def xray(shapes: list, color=None, stroke=0.5):
654    """Draw debug rectangles for given shapes.
655
656    Args:
657        shapes: List of shape tuples.
658        color: Optional color for rectangles.
659        stroke: Stroke width for rectangles.
660    """
661    with drawBot.savedState():
662        for shape in helpers.flattenTuples(shapes):
663            c = color or [random.uniform(0, 1) for _ in range(3)]
664            if stroke:
665                drawBot.strokeWidth(stroke)
666                drawBot.stroke(*c)
667                drawBot.fill(None)
668            else:
669                drawBot.fill(*c)
670            drawBot.rect(*shape)
671
672
673def draftBar(
674    frame: tuple,
675    lines=1,
676    position: Literal["top", "bottom"] = "top",
677    debug=False,
678):
679    """
680    Draft header/footer for given number of `lines`.
681
682    - `font()`, `fontSize` and `lineHeight` must already be set
683
684    Args:
685        frame: Frame tuple.
686        lines: Number of lines for the bar.
687        position: 'top' or 'bottom' of the frame.
688        debug: If True, draw debug overlay.
689
690    Returns:
691        Coords tuple for the draft bar.
692    """
693    frameX, frameY, frameW, frameH = frame
694    txtDummy = ("").join(["\n" for _ in range(lines)])
695
696    _, boxH = drawBot.textSize(txtDummy, width=frameW)
697
698    if position == "bottom":
699        coords = frameX, frameY, frameW, boxH
700    else:
701        coords = frameX, frameY + frameH - boxH, frameW, boxH
702
703    if debug:
704        xray(coords)
705
706    return coords
707
708
709def draftBody(
710    frame: tuple,
711    header: tuple = None,
712    footer: tuple = None,
713    gap=4,
714    unit: UnitType = "mm",
715    debug=False,
716):
717    """
718    Substract header/footer.
719
720    - Returns `coords` tuple of body
721
722    Args:
723        frame: Frame tuple.
724        header: Header rectangle.
725        footer: Footer rectangle.
726        gap: Gap between sections.
727        unit: Unit type for gap.
728        debug: If True, draw debug overlay.
729
730    Returns:
731        Coords tuple for the body area.
732    """
733    if unit == "mm":
734        gap = mm(gap)
735
736    frameX, frameY, frameW, frameH = frame
737    h, y = frameH, frameY
738
739    if header:
740        _, _, _, headerH = header
741        h -= headerH + gap
742
743    if footer:
744        _, _, _, footerH = footer
745        delta = footerH + gap
746        h -= delta
747        y += delta
748
749    coords = frameX, y, frameW, h
750
751    if debug:
752        xray(coords)
753
754    return coords