0
# MutatorMath
1

2
MutatorMath is a Python library that provides advanced mathematical tools for piecewise linear interpolation in n-dimensional design spaces with any number of masters. Originally developed for font interpolation, it can handle any arithmetic objects that support basic mathematical operations. The library enables complex interpolation scenarios including on-axis and off-axis calculations, anisotropic coordinates, and multi-dimensional design spaces with named axes.
3

4
## Package Information
5

6
- **Package Name**: MutatorMath
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install MutatorMath`
10
- **Dependencies**: fonttools>=3.32.0, defcon>=0.3.5, fontMath>=0.4.8
11

12
## Core Imports
13

14
```python
15
from mutatorMath import Location, Mutator
16
```
17

18
For advanced functionality:
19

20
```python
21
from mutatorMath.objects.location import Location
22
from mutatorMath.objects.mutator import Mutator, buildMutator
23
from mutatorMath.objects.bender import Bender
24
```
25

26
## Basic Usage
27

28
```python
29
from mutatorMath import Location, Mutator
30
from mutatorMath.objects.mutator import buildMutator
31

32
# Create locations in design space
33
master1_loc = Location(weight=100, width=75)
34
master2_loc = Location(weight=900, width=75) 
35
master3_loc = Location(weight=100, width=125)
36
master4_loc = Location(weight=900, width=125)
37

38
# Create sample objects (can be any arithmetic objects)
39
master1_obj = 50    # thin, narrow
40
master2_obj = 200   # bold, narrow  
41
master3_obj = 60    # thin, wide
42
master4_obj = 180   # bold, wide
43

44
# Build mutator from (location, object) pairs
45
items = [
46
    (master1_loc, master1_obj),
47
    (master2_loc, master2_obj), 
48
    (master3_loc, master3_obj),
49
    (master4_loc, master4_obj)
50
]
51

52
bias, mutator = buildMutator(items)
53

54
# Interpolate at any location in design space
55
target = Location(weight=500, width=100)
56
result = mutator.makeInstance(target)
57
print(result)  # Interpolated value
58
```
59

60
## Architecture
61

62
MutatorMath is organized into two main subpackages:
63

64
- **objects**: General calculation tools for location-based interpolation that work with any arithmetic objects
65
- **ufo**: Specialized tools for processing UFO (Unified Font Object) data with designspace document support
66

67
The core design uses Location objects to represent n-dimensional coordinates and Mutator objects to perform interpolation calculations based on master-instance relationships.
68

69
## Capabilities
70

71
### Core Objects
72

73
Foundation classes for multi-dimensional interpolation including Location objects for coordinate representation, Mutator objects for interpolation calculations, and Bender objects for non-linear transformations.
74

75
```python { .api }
76
class Location(dict):
77
    """N-dimensional location object with arithmetic operations."""
78
    def __init__(self, **kwargs): ...
79
    def isOrigin(self) -> bool: ...
80
    def expand(self, other): ...
81

82
class Mutator(dict):
83
    """Main interpolation class for calculating instances from masters."""
84
    def __init__(self): ...
85
    def makeInstance(self, location) -> any: ...
86
    def setNeutral(self, obj): ...
87
    def setBias(self, location): ...
88

89
def buildMutator(items, axes=None, bias=None) -> tuple[Location, Mutator]:
90
    """Build a mutator with (location, obj) pairs. Returns (bias, mutator) tuple."""
91

92
class Bender(object):
93
    """Non-linear transformation object for warping design spaces."""
94
    def __init__(self, axes): ...
95
    def __call__(self, location) -> Location: ...
96
```
97

98
[Core Objects](./core-objects.md)
99

100
### UFO Tools
101

102
Specialized tools for font interpolation including designspace document processing, UFO instance generation, and XML-based design space descriptions.
103

104
```python { .api }
105
def build(documentPath, outputUFOFormatVersion=2, roundGeometry=True, 
106
          verbose=True, logPath=None, progressFunc=None) -> list:
107
    """Simple builder for UFO designspaces."""
108

109
class DesignSpaceDocumentWriter(object):
110
    """Writer for designspace XML documents."""
111
    def __init__(self, path, toolVersion=3, verbose=False): ...
112
    def save(self, pretty=True): ...
113

114
class DesignSpaceDocumentReader(object):
115
    """Reader and processor for designspace XML documents."""
116
    def __init__(self, path, ufoVersion=2, roundGeometry=True, 
117
                 verbose=True, logPath=None, progressFunc=None): ...
118
    def process(self): ...
119
```
120

121
[UFO Tools](./ufo-tools.md)
122

123
## Types
124

125
```python { .api }
126
class MutatorError(Exception):
127
    """Exception class for MutatorMath-specific errors."""
128
    def __init__(self, msg, obj=None): ...
129
```