lib.fonts

  1import re
  2import os
  3import drawBot
  4from typing import Literal, TypeAlias
  5from pathlib import Path
  6from loguru import logger
  7from icecream import ic
  8
  9from lib import content, helpers, layout
 10
 11FontStyle: TypeAlias = Literal["upright", "italic"]
 12"""Font style (slope) alias."""
 13
 14FontType: TypeAlias = Literal[
 15    "upright", "italic", "display", "text", "thin", "thick", "any"
 16]
 17"""Font type alias."""
 18
 19TextAlign: TypeAlias = Literal["left", "center", "right"]
 20"""Text alignment alias."""
 21
 22FontFeature: TypeAlias = Literal[
 23    "calt",
 24    "case",
 25    "dlig",
 26    "frac",
 27    "liga",
 28    "kern",
 29    "lnum",
 30    "onum",
 31    "ordn",
 32    "pnum",
 33    "ss01",
 34    "ss02",
 35    "ss03",
 36    "ss04",
 37    "ss05",
 38    "ss06",
 39    "ss07",
 40    "ss08",
 41    "ss09",
 42    "ss10",
 43    "subs",
 44    "sups",
 45    "titl",
 46    "tnum",
 47]
 48"""OpenType font feature code alias."""
 49
 50
 51def getFontName(fontPath: str) -> str:
 52    """
 53    Get the font name without extension.
 54
 55    Args:
 56        fontPath: Path to the font file.
 57
 58    Example:
 59        `/folder/fileName-styleName.otf` => `fileName-styleName`
 60    """
 61    fullName = Path(fontPath).stem
 62    return fullName
 63
 64
 65def getFontsFromFolder(fontFolder: str) -> list[str]:
 66    """
 67    Get all font file paths from a folder.
 68
 69    Args:
 70        fontFolder: Path to the folder containing font files.
 71
 72    Returns:
 73        List of font file paths with .otf or .ttf extensions.
 74    """
 75    fontPaths = []
 76    for root, dirs, files in os.walk(fontFolder):
 77        files.sort()
 78        for fileName in files:
 79            basePath, ext = os.path.splitext(fileName)
 80            if ext in [".otf", ".ttf"]:
 81                fontPaths.append(os.path.join(root, fileName))
 82    return fontPaths
 83
 84
 85def getFonts(source: str) -> list[str]:
 86    """
 87    Get font file paths from a source, which can be a directory, file, or list of files.
 88
 89    Args:
 90        source: Directory path, file path, or list of file paths.
 91
 92    Returns:
 93        List of valid font file paths.
 94    """
 95    isMultiple = type(source) is list
 96    isSingle = isinstance(source, str)
 97
 98    if isSingle:
 99        if helpers.isDirectory(source):
100            return getFontsFromFolder(source)
101        elif helpers.isFile(source):
102            return [source]
103        else:
104            logger.warning("[Fonts Not Found] {}", source)
105    elif isMultiple:
106        # Check if files exist
107        def check(file):
108            if helpers.isFile(file):
109                return file
110            else:
111                print("File not found: ", file)
112
113        mapped = [check(file) for file in source]
114        # Omit None
115        return [file for file in mapped if file]
116
117
118def parseNameObject(fontString: str, separate=False) -> str | dict:
119    """
120    Parse a font string into its components.
121
122    Args:
123        fontString: The font string or path.
124        separate: If True, returns a dict of components. If False, returns the full name.
125
126    Returns:
127    - If `separate` is True, returns a dict with keys:
128        - `fullName`: e.g. `Stabil Grotesk 400 Regular`
129        - `familyName`: e.g. `Stabil Grotesk`
130        - `shortName`: e.g. `400 Regular`
131        - `styleNumber`: e.g. `400`
132        - `styleName`: e.g. `Regular`
133    - If `separate` is False, returns the `fullName` string.
134    """
135    fontName = getFontName(fontString)
136    familyName, *suffix = fontName.split("-")
137
138    # KUniforma => Uniforma
139    familyName = re.sub(r"^\(?K\)?", "", familyName)
140    # StabilGrotesk => Stabil Grotesk
141    familyName = content.parseCamelCase(familyName).strip()
142
143    # ['55RegularItalic'] => '50RegularItalic'
144    suffix = "".join(suffix).strip()
145    hasStyleName = re.search(r"\D+", suffix)
146    hasStyleNumber = re.search(r"\d+", suffix)
147
148    # RegularItalic => Regular Italic
149    styleName = content.parseCamelCase(hasStyleName.group()) if hasStyleName else None
150    # 55/None
151    styleNumber = hasStyleNumber.group() if hasStyleNumber else None
152    # [None, 'Regular Italic] => ['Regular Italic']
153    omitBlank = [part for part in [styleNumber, styleName] if part]
154    fullName = (" ").join([familyName, *omitBlank])
155    shortName = (" ").join(omitBlank)
156
157    if separate:
158        return {
159            "fullName": fullName,  # Stabil Grotesk 400 Regular
160            "familyName": familyName,  # Stabil Grotesk
161            "shortName": shortName,  # 400 Regular
162            "styleNumber": styleNumber,  # 400
163            "styleName": styleName,  # Regular
164        }
165    else:
166        return fullName
167
168
169def parseStyle(fontSize: int | tuple[int, int], leading=1, tracking=0, separator="/"):
170    """
171    Returns human readable font properties.
172
173    Args:
174        fontSize: Font size as int or tuple for range
175            - `(int) 72` or as range `(tuple) 72, 12`
176        leading: Line height multiplier or value
177            - lineHeight `int` or leading `float`
178        tracking: Tracking value.
179        separator: Separator string.
180    """
181    if isinstance(fontSize, tuple):
182        # Skip showing lineHeight for range of fontSizes
183        fsAndLh = "—".join(map(str, helpers.pickExtremes(fontSize)))
184    else:
185        # Assume it’s leading if ≤ 2
186        lineHeight = fontSize * leading if leading <= 2 else leading
187        fsAndLh = f"{round(fontSize)}{separator}{round(lineHeight)}"
188
189    if tracking:
190        return f"{fsAndLh}{separator}{round(tracking, 1)}"
191    else:
192        # Round both
193        return fsAndLh
194
195
196def getStyleNumber(fontString: str, format: Literal["str", "int"] = "str") -> str | int:
197    """
198    Get the style number from a font string.
199
200    Args:
201        fontString: The font string or style number.
202        format: Output format, string or integer.
203    """
204    isStyleNumber = fontString.isnumeric()
205
206    styleNumber = (
207        fontString
208        if isStyleNumber
209        else parseNameObject(fontString, separate=True)["styleNumber"]
210    )
211
212    return int(styleNumber) if format == "int" else str(styleNumber)
213
214
215def findFontByNumber(fontList: list[str], fontNumber: int) -> str | None:
216    """
217    Find the font in fontList with the closest style number to fontNumber.
218
219    Args:
220        fontList: List of font strings.
221        fontNumber: Target style number.
222
223    Returns:
224        The font string with the closest style number, or `None` if not found.
225    """
226    # Get numbers, None if not found
227    numbers = [getStyleNumber(font, format="int") for font in fontList]
228
229    # Compact array
230    numbers = [number for number in numbers if isinstance(number, int)]
231
232    if len(numbers):
233        closest = helpers.findClosestValue(numbers, fontNumber)
234        closestIndex = numbers.index(closest)
235        return fontList[closestIndex]
236
237
238def isFontType(fontPath: str, criterion: FontType) -> bool:
239    """
240    Check if a font matches a given FontType criterion.
241
242    Args:
243        fontPath: Path to the font file.
244        criterion: FontType criterion.
245
246    Returns:
247        True if the font matches the criterion, False otherwise.
248    """
249    # Special case
250    if criterion == "any":
251        return True
252
253    styleNumber = getStyleNumber(fontPath)
254    return criterion in getFontType(styleNumber)
255
256
257def isDisplay(fontString: str) -> bool:
258    """Returns True if the font is of type `display`."""
259    return isFontType(fontString, "display")
260
261
262def getFontType(fontString: str) -> list[FontType]:
263    """
264    Get the list of `FontType` that match the font's style number. See source for regex patterns.
265
266    Args:
267        fontString: The font string or path.
268
269    Returns:
270        List of matching FontTypes.
271    """
272
273    def _isMatch(pattern: str) -> bool:
274        return bool(re.compile(rf"^{pattern}").search(styleNumber))
275
276    fontTypes = {
277        "upright": r"\d0",
278        "italic": r"\d5",
279        "display": "[^4-6]",
280        "text": "[4-6]",
281        "thin": "[1-3]",
282        "thick": "[7-9]",
283    }
284
285    styleNumber = getStyleNumber(fontString)
286    return [fontType for [fontType, pattern] in fontTypes.items() if _isMatch(pattern)]
287
288
289def filterFonts(
290    fonts: list[str],
291    criteria: FontType | list[FontType] = "upright",
292    strategy: helpers.Strategy = "pick",
293) -> list[str]:
294    """
295    Filter fonts by given criteria and strategy.
296
297    Args:
298        fonts: List of font strings.
299        criteria: `FontType` or list of FontTypes to filter by.
300        strategy: Filtering strategy, "pick" or "omit".
301
302    Returns:
303        List of filtered font strings.
304    """
305
306    def _evaluate(predicate: bool):
307        "Inverse logic for `omit` strategy"
308        return predicate if strategy == "pick" else not predicate
309
310    def _fontsForCriterion(criterion: FontType) -> list[str]:
311        return [font for font in fonts if _evaluate(isFontType(font, criterion))]
312
313    criteria = helpers.coerceList(criteria)
314    # Groups of matches
315    allMatches = [_fontsForCriterion(criterion) for criterion in criteria]
316    # Intersect matches and sort them by number
317    return helpers.intersect(allMatches)
318
319
320def groupFontsBySlope(fonts: list[str], reverseOrder=True):
321    """
322    Group fonts by slope (upright/italic).
323
324    Args:
325        fonts: List of font strings.
326        reverseOrder: If True, reverse the order of each group.
327
328    Returns:
329        Tuple of (upright_fonts, italic_fonts).
330    """
331    fontsUpright = filterFonts(fonts, "upright")
332    fontsItalic = filterFonts(fonts, "italic")
333
334    groups = (fontsUpright, fontsItalic)
335
336    if reverseOrder:
337        for group in groups:
338            group.reverse()
339
340    return groups
341
342
343def groupFontsByWeight(fonts: list[str], reverseOrder=True):
344    """
345    Group fonts by weight, pairing upright and italic fonts.
346
347    Args:
348        fonts: List of font strings.
349        reverseOrder: If True, reverse the order of each group.
350
351    Returns:
352        List of tuples pairing upright and italic fonts by weight.
353    """
354    fontsUpright, fontsItalic = groupFontsBySlope(
355        fonts=fonts, reverseOrder=reverseOrder
356    )
357
358    return list(zip(fontsUpright, fontsItalic))
359
360
361def fitBinary(
362    text: str,
363    container: tuple,
364    leading: float = 1,
365    letterSpacing: int = 0,
366    isFluid: bool = False,
367    saveState: bool = True,
368    debug: bool = False,
369    precision: int = 0,
370) -> tuple:
371    """
372    Find the largest font size to fit text in a container, using a binary search algorithm. Calculates font size in integer space for performance by default, can be adjusted with `precision`.
373
374    Args:
375        text: The text string to fit.
376        container: The container as a tuple of `(width, height)` or `(x, y, width, height)`.
377        leading: Line height multiplier (default: 1).
378        letterSpacing: Letter spacing value (default: 0).
379        isFluid: If True, allows text wrapping to fit width; if False, fits text on a single line.
380        saveState: If True, preserves the current DrawBot drawing state.
381        debug: If True, outputs debug information.
382        precision: Number of decimal places for font size (0 = integer, 1 = tenths, 2 = hundredths).
383
384    Returns:
385        A tuple containing:
386            - fontSize: The maximum font size that fits.
387            - lineHeight: The calculated line height for this font size.
388            - tracking: The calculated tracking for this font size.
389            - textW: The width of the rendered text at this size.
390            - textH: The height of the rendered text at this size.
391    """
392
393    def _getDimensions(size):
394        def modifyState():
395            drawBot.fontSize(size)
396            drawBot.lineHeight(lead(size))
397            drawBot.tracking(track(size))
398            textW, textH = drawBot.textSize(text, width=containerW if isFluid else None)
399            # Compensate for tracking
400            return textW - track(size), textH
401
402        # Used for preparatory calculations
403        if saveState:
404            # Important! savedState() triggers newPage() for blank drawing
405            with drawBot.savedState():
406                return modifyState()
407        else:
408            return modifyState()
409
410    def _canFit(fs):
411        textW, textH = _getDimensions(fs)
412        return textW <= containerW and textH <= containerH
413
414    lead = lambda fs: fs * leading
415    track = lambda fs: letterSpacing * (fs / 1000)
416
417    containerW, containerH = layout.toDimensions(container)
418
419    # Adapt precision based on parameter (default to integer search)
420    factor = 10**precision
421
422    # Convert to integer space for binary search
423    low, high = 0, int(max(containerW, containerH) * factor)
424    maxFs = -1
425    triesNo, triesMax = 0, 100 + (precision * 10)  # More precision needs more tries
426
427    while low <= high and triesNo < triesMax:
428        triesNo += 1
429        fs_int = (low + high) // 2
430        fs = fs_int / factor  # Convert back to float for testing
431
432        if _canFit(fs):
433            maxFs = fs
434            low = fs_int + 1
435        else:
436            high = fs_int - 1
437
438        if triesNo == triesMax:
439            logger.warning(f"{triesMax} tries exceeded")
440
441    if debug:
442        logger.trace(f"Found after {triesNo} attempts: {maxFs}")
443
444    # Round to desired precision
445    maxFs = round(maxFs, precision) if precision > 0 else int(maxFs)
446
447    return maxFs, lead(maxFs), track(maxFs), *_getDimensions(maxFs)
448
449
450def fitBinaryFS(
451    contents: list,
452    container: tuple,
453    fontProps: dict,
454    maxSize: int = None,
455    isFluid=False,
456    debug=False,
457) -> tuple[drawBot.drawBotDrawingTools.FormattedString, int]:
458    """
459    Find the maximum font size for a FormattedString that fits in the container.
460
461    Args:
462        contents: List of (text, fontPath) tuples.
463        container: The container dimensions.
464        fontProps: Dictionary of font properties.
465        maxSize: Clamp maximum font size.
466        isFluid: If True, use fluid width.
467        debug: If True, print debug information.
468
469    Returns:
470        Tuple of (FormattedString, fontSize).
471    """
472
473    def _createFS(formattedProps: dict) -> drawBot.drawBotDrawingTools.FormattedString:
474        """
475        Create a FormattedString with the given properties.
476
477        Args:
478            formattedProps: Dictionary of formatting properties.
479
480        Returns:
481            FormattedString object.
482        """
483        dummy = drawBot.FormattedString(**formattedProps)
484        for [text, font] in contents:
485            dummy.append(text, font=font)
486        return dummy
487
488    def _getFormattedProps(fontSize: int, factor=10):
489        """
490        Get formatted properties for a given font size.
491
492        Args:
493            fontSize: Font size.
494            factor: Tracking factor.
495
496        Returns:
497            Dictionary of formatted properties.
498        """
499        lead = lambda fs: fs * fontProps.get("leading", 1)
500        track = lambda fs: (fs / factor) * fontProps.get("tracking", 0)
501        textAlign = fontProps.get("align", "left")
502        tabs = fontProps.get("tabs")
503
504        props = {
505            "fontSize": fontSize,
506            "lineHeight": lead(fontSize),
507            "tracking": track(fontSize),
508            "align": textAlign,
509            "tabs": tabs,
510        }
511
512        rgbFill = fontProps.get("fill")
513        cmykFill = fontProps.get("cmykFill")
514
515        if rgbFill:
516            props["fill"] = rgbFill
517        elif cmykFill:
518            props["cmykFill"] = cmykFill
519
520        return props
521
522    def _canFitString(fontSize: int) -> bool:
523        """
524        Check if a FormattedString of a given font size fits in the container.
525
526        Args:
527            fontSize: Font size.
528
529        Returns:
530            True if it fits, False otherwise.
531        """
532        dummy = _createFS(_getFormattedProps(fontSize))
533        dummySize = drawBot.textSize(dummy, width=containerW if isFluid else None)
534        return layout.canFitInside(containerSize, dummySize)
535
536    contents = helpers.coerceList(contents, strict=True)
537    containerSize = containerW, _ = layout.toDimensions(container)
538    low, high = 0, min(containerSize)
539    best = -1
540    triesNo, triesMax = 0, 100
541
542    while low <= high and triesNo < triesMax:
543        triesNo += 1
544        mid = (low + high) // 2
545
546        if _canFitString(fontSize=mid):
547            best = mid
548            low = mid + 1
549        else:
550            high = mid - 1
551
552        if triesNo == triesMax:
553            logger.debug(f"{triesMax} tries exceeded")
554
555    if debug:
556        logger.debug(f"Found after {triesNo} attempts:", best)
557
558    if maxSize:
559        best = min(best, maxSize)
560
561    return _createFS(_getFormattedProps(best)), best
562
563
564def makeTabs(container: tuple | int, n=1, mode: Literal["apply", "kwargs"] = "apply"):
565    """
566    Make `n` tabs based on `container` width.
567
568    Args:
569        container: Accepts `coords` tuple or `width` int.
570        n: Number of tabs.
571        mode: `apply` to set instantly via drawBot.tabs(), `kwargs` for FormattedString().
572
573    Returns:
574    - If mode is `apply`, sets tabs and returns None.
575    - If mode is `kwargs`, returns a list of tab positions and alignments.
576    """
577    width = layout.toWidth(container)
578    advanceW = width / n
579    result = []
580
581    for tab in range(1, n + 1):
582        isTabLast = tab == n
583        tabAlign = "right" if isTabLast else "center"
584        result.append((tab * advanceW, tabAlign))
585
586    if mode == "apply":
587        drawBot.tabs(*result)
588    else:
589        return result