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