shadowfacts/fonttools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source 
- independent reader / writer object for designspace documents.
- imports and exports easy to subclass objects for instance, source and axis data.
- roundtrips
- intended to be compatible with use in MutatorMath, Superpolatpor and varlib.
This commit is contained in:
Erik 2016-11-15 13:27:39 +01:00
commit 2fbdd37362
5 changed files with 1033 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored Normal file
View File

@ -0,0 +1 @@
test.designspace

724
Lib/designSpaceDocument/__init__.py Normal file
View File

@ -0,0 +1,724 @@
# -*- coding: utf-8 -*-
import os
import xml.etree.ElementTree as ET
"""
designSpaceDocument
- read and write designspace files
- axes must be defined.
- warpmap is stored in its axis element
"""
__all__ = [
'DesignSpaceDocumentError', 'BaseDocReader', 'DesignSpaceDocument',
'SourceDescriptor', 'InstanceDescriptor',
'AxisDescriptor', 'BaseDocReader', 'BaseDocWriter']
class DesignSpaceDocumentError(Exception):
def __init__(self, msg, obj=None):
self.msg = msg
self.obj = obj
def __str__(self):
return repr(self.msg) + repr(self.obj)
def _indent(elem, whitespace=" ", level=0):
# taken from http://effbot.org/zone/element-lib.htm#prettyprint
i = "\n" + level * whitespace
if len(elem):
if not elem.text or not elem.text.strip():
elem.text = i + whitespace
if not elem.tail or not elem.tail.strip():
elem.tail = i
for elem in elem:
_indent(elem, whitespace, level+1)
if not elem.tail or not elem.tail.strip():
elem.tail = i
else:
if level and (not elem.tail or not elem.tail.strip()):
elem.tail = i
class SimpleDescriptor(object):
""" Containers for a bunch of attributes"""
def compare(self, other):
# test if this object contains the same data as the other
for attr in self._attrs:
try:
#print getattr(self, attr), getattr(other, attr)
assert(getattr(self,attr) == getattr(other,attr))
except AssertionError:
print "failed attribute", attr, getattr(self, attr), "!=", getattr(other, attr)
class SourceDescriptor(SimpleDescriptor):
"""Simple container for data related to the source"""
flavor="source"
_attrs = [ 'path', 'name',
'location', 'copyLib',
'copyGroups', 'copyFeatures',
'muteKerning', 'muteInfo',
'mutedGlyphNames',
'familyName', 'styleName']
def __init__(self):
self.path = None
self.name = None
self.location = None
self.copyLib = False
self.copyInfo = False
self.copyGroups = False
self.copyFeatures = False
self.muteKerning = False
self.muteInfo = False
self.mutedGlyphNames = []
self.familyName = None
self.styleName = None
class InstanceDescriptor(SimpleDescriptor):
"""Simple container for data related to the instance"""
flavor="instance"
_attrs = [ 'path', 'name',
'location', 'familyName',
'styleName', 'postScriptFontName',
'styleMapFamilyName',
'styleMapStyleName',
'kerning', 'info']
def __init__(self):
self.path = None
self.name = None
self.location = None
self.familyName = None
self.styleName = None
self.postScriptFontName = None
self.styleMapFamilyName = None
self.styleMapStyleName = None
self.glyphs = {}
self.kerning = True
self.info = True
class AxisDescriptor(SimpleDescriptor):
"""Simple container for the axis data"""
flavor="axis"
_attrs = ['tag', 'name', 'maximum', 'minimum', 'default', 'map']
def __init__(self):
self.tag = None # opentype tag for this axis
self.name = None # name of the axis used in locations
self.labelNames = {} # names for UI purposes, if this is not a standard axis,
self.minimum = None
self.maximum = None
self.default = None
self.map = []
class BaseDocWriter(object):
_whiteSpace = " "
axisDescriptorClass = AxisDescriptor
sourceDescriptorClass = SourceDescriptor
instanceDescriptorClass = InstanceDescriptor
def __init__(self, documentPath, documentObject):
self.path = documentPath
self.documentObject = documentObject
self.toolVersion = 3
self.root = ET.Element("designspace")
self.root.attrib['format'] = "%d"%self.toolVersion
self.root.append(ET.Element("axes"))
self.root.append(ET.Element("sources"))
self.root.append(ET.Element("instances"))
self.axes = []
def newDefaultLocation(self):
loc = {}
for axisDescriptor in self.axes:
loc[axisDescriptor.name] = axisDescriptor.default
return loc
def write(self, pretty=True):
for axisObject in self.documentObject.axes:
self._addAxis(axisObject)
for sourceObject in self.documentObject.sources:
self._addSource(sourceObject)
for instanceObject in self.documentObject.instances:
self._addInstance(instanceObject)
if pretty:
_indent(self.root, whitespace=self._whiteSpace)
tree = ET.ElementTree(self.root)
tree.write(self.path, encoding=u"utf-8", method='xml', xml_declaration=True)
def _makeLocationElement(self, locationObject, name=None):
""" Convert Location dict to a locationElement."""
locElement = ET.Element("location")
if name is not None:
locElement.attrib['name'] = name
defaultLoc = self.newDefaultLocation()
validatedLocation = {}
for axisName, axisValue in defaultLoc.items():
# update the location dict with missing default axis values
if not axisName in locationObject:
validatedLocation[axisName] = axisValue
else:
validatedLocation[axisName] = locationObject[axisName]
for dimensionName, dimensionValue in validatedLocation.items():
dimElement = ET.Element('dimension')
dimElement.attrib['name'] = dimensionName
if type(dimensionValue)==tuple:
dimElement.attrib['xvalue'] = self.intOrFloat(dimensionValue[0])
dimElement.attrib['yvalue'] = self.intOrFloat(dimensionValue[1])
else:
dimElement.attrib['xvalue'] = self.intOrFloat(dimensionValue)
locElement.append(dimElement)
return locElement, validatedLocation
def intOrFloat(self, num):
if int(num) == num:
return "%d"%num
return "%f"%num
def _addAxis(self, axisObject):
self.axes.append(axisObject)
axisElement = ET.Element('axis')
axisElement.attrib['tag'] = axisObject.tag
axisElement.attrib['name'] = axisObject.name
axisElement.attrib['minimum'] = str(axisObject.minimum)
axisElement.attrib['maximum'] = str(axisObject.maximum)
axisElement.attrib['default'] = str(axisObject.default)
for languageCode, labelName in axisObject.labelNames.items():
languageElement = ET.Element('labelName')
languageElement.attrib[u'xml:lang'] = languageCode
languageElement.text = labelName
axisElement.append(languageElement)
if axisObject.map:
for inputValue, outputValue in axisObject.map:
mapElement = ET.Element('map')
mapElement.attrib['input'] = str(inputValue)
mapElement.attrib['output'] = str(outputValue)
axisElement.append(mapElement)
self.root.findall('.axes')[0].append(axisElement)
def _addInstance(self, instanceObject):
instanceElement = ET.Element('instance')
if instanceObject.name is not None:
instanceElement.attrib['name'] = instanceObject.name
if instanceObject.familyName is not None:
instanceElement.attrib['familyname'] = instanceObject.familyName
if instanceObject.styleName is not None:
instanceElement.attrib['stylename'] = instanceObject.styleName
if instanceObject.location is not None:
locationElement, instanceObject.location = self._makeLocationElement(instanceObject.location)
instanceElement.append(locationElement)
if instanceObject.path is not None:
pathRelativeToDocument = os.path.relpath(instanceObject.path, os.path.dirname(self.path))
instanceElement.attrib['filename'] = pathRelativeToDocument
if instanceObject.postScriptFontName is not None:
instanceElement.attrib['postscriptfontname'] = instanceObject.postScriptFontName
if instanceObject.styleMapFamilyName is not None:
instanceElement.attrib['stylemapfamilyname'] = instanceObject.styleMapFamilyName
if instanceObject.styleMapStyleName is not None:
instanceElement.attrib['stylemapstylename'] = instanceObject.styleMapStyleName
if instanceObject.glyphs:
if instanceElement.findall('.glyphs') == []:
glyphsElement = ET.Element('glyphs')
instanceElement.append(glyphsElement)
glyphsElement = instanceElement.findall('.glyphs')[0]
for glyphName, data in instanceObject.glyphs.items():
glyphElement = self._writeGlyphElement(instanceElement, instanceObject, glyphName, data)
glyphsElement.append(glyphElement)
if instanceObject.kerning:
kerningElement = ET.Element('kerning')
instanceElement.append(kerningElement)
if instanceObject.info:
infoElement = ET.Element('info')
instanceElement.append(infoElement)
self.root.findall('.instances')[0].append(instanceElement)
def _addSource(self, sourceObject):
sourceElement = ET.Element("source")
pathRelativeToDocument = os.path.relpath(sourceObject.path, os.path.dirname(self.path))
sourceElement.attrib['filename'] = pathRelativeToDocument
if sourceObject.name is not None:
sourceElement.attrib['name'] = sourceObject.name
if sourceObject.familyName is not None:
sourceElement.attrib['familyname'] = sourceObject.familyName
if sourceObject.styleName is not None:
sourceElement.attrib['stylename'] = sourceObject.styleName
if sourceObject.copyLib:
libElement = ET.Element('lib')
libElement.attrib['copy'] = "1"
sourceElement.append(libElement)
if sourceObject.copyGroups:
groupsElement = ET.Element('groups')
groupsElement.attrib['copy'] = "1"
sourceElement.append(groupsElement)
if sourceObject.copyFeatures:
featuresElement = ET.Element('features')
featuresElement.attrib['copy'] = "1"
sourceElement.append(featuresElement)
if sourceObject.copyInfo or sourceObject.muteInfo:
infoElement = ET.Element('info')
if sourceObject.copyInfo:
infoElement.attrib['copy'] = "1"
if sourceObject.muteInfo:
infoElement.attrib['mute'] = "1"
sourceElement.append(infoElement)
if sourceObject.muteKerning:
kerningElement = ET.Element("kerning")
kerningElement.attrib["mute"] = '1'
sourceElement.append(kerningElement)
if sourceObject.mutedGlyphNames:
for name in sourceObject.mutedGlyphNames:
glyphElement = ET.Element("glyph")
glyphElement.attrib["name"] = name
glyphElement.attrib["mute"] = '1'
sourceElement.append(glyphElement)
locationElement, sourceObject.location = self._makeLocationElement(sourceObject.location)
sourceElement.append(locationElement)
self.root.findall('.sources')[0].append(sourceElement)
def _writeGlyphElement(self, instanceElement, instanceObject, glyphName, data):
glyphElement = ET.Element('glyph')
if data.get('mute'):
glyphElement.attrib['mute'] = "1"
if data.get('unicodeValue') is not None:
glyphElement.attrib['unicode'] = hex(data.get('unicodeValue'))
if data.get('instanceLocation') is not None:
locationElement, data['instanceLocation'] = self._makeLocationElement(data.get('instanceLocation'))
glyphElement.append(locationElement)
if glyphName is not None:
glyphElement.attrib['name'] = glyphName
if data.get('note') is not None:
noteElement = ET.Element('note')
noteElement.text = data.get('note')
glyphElement.append(noteElement)
if data.get('masters') is not None:
mastersElement = ET.Element("masters")
for m in data.get('masters'):
masterElement = ET.Element("master")
if m.get('glyphName') is not None:
masterElement.attrib['glyphname'] = m.get('glyphName')
if m.get('font') is not None:
masterElement.attrib['source'] = m.get('font')
if m.get('location') is not None:
locationElement, m['location'] = self._makeLocationElement(m.get('location'))
masterElement.append(locationElement)
mastersElement.append(masterElement)
glyphElement.append(mastersElement)
return glyphElement
class BaseDocReader(object):
axisDescriptorClass = AxisDescriptor
sourceDescriptorClass = SourceDescriptor
instanceDescriptorClass = InstanceDescriptor
def __init__(self, documentPath, documentObject):
self.path = documentPath
self.documentObject = documentObject
self.documentObject.formatVersion = 0
tree = ET.parse(self.path)
self.root = tree.getroot()
self.documentObject.formatVersion = int(self.root.attrib.get("format", 0))
self.axes = []
self.sources = []
self.instances = []
self.axisDefaults = {}
def read(self):
self.readAxes()
self.readSources()
self.readInstances()
def getSourcePaths(self, makeGlyphs=True, makeKerning=True, makeInfo=True):
paths = []
for name in self.documentObject.sources.keys():
paths.append(self.documentObject.sources[name][0].path)
return paths
def newDefaultLocation(self):
loc = {}
for axisDescriptor in self.axes:
loc[axisDescriptor.name] = axisDescriptor.default
return loc
def readAxes(self):
# read the axes elements, including the warp map.
axes = []
for axisElement in self.root.findall(".axes/axis"):
axisObject = self.axisDescriptorClass()
axisObject.name = axisElement.attrib.get("name")
axisObject.minimum = float(axisElement.attrib.get("minimum"))
axisObject.maximum = float(axisElement.attrib.get("maximum"))
# we need to check if there is an attribute named "initial"
if axisElement.attrib.get("default") is None:
if axisElement.attrib.get("initial") is not None:
axisObject.default = float(axisElement.attrib.get("initial"))
else:
axisObject.default = axisObject.minimum
else:
axisObject.default = float(axisElement.attrib.get("default"))
axisObject.tag = axisElement.attrib.get("tag")
for mapElement in axisElement.findall('map'):
a = float(mapElement.attrib['input'])
b = float(mapElement.attrib['output'])
axisObject.map.append((a,b))
self.documentObject.axes.append(axisObject)
self.axisDefaults[axisObject.name] = axisObject.default
def readSources(self):
for sourceElement in self.root.findall(".sources/source"):
filename = sourceElement.attrib.get('filename')
sourcePath = os.path.abspath(os.path.join(os.path.dirname(self.path), filename))
sourceName = sourceElement.attrib.get('name')
sourceObject = self.sourceDescriptorClass()
sourceObject.path = sourcePath
sourceObject.name = sourceName
familyName = sourceElement.attrib.get("familyname")
if familyName is not None:
sourceObject.familyName = familyName
styleName = sourceElement.attrib.get("stylename")
if styleName is not None:
sourceObject.styleName = styleName
sourceObject.location = self.locationFromElement(sourceElement)
for libElement in sourceElement.findall('.lib'):
if libElement.attrib.get('copy') == '1':
sourceObject.copyLib = True
for groupsElement in sourceElement.findall('.groups'):
if groupsElement.attrib.get('copy') == '1':
sourceObject.copyGroups = True
for infoElement in sourceElement.findall(".info"):
if infoElement.attrib.get('copy') == '1':
sourceObject.copyInfo = True
if infoElement.attrib.get('mute') == '1':
sourceObject.muteInfo = True
for featuresElement in sourceElement.findall(".features"):
if featuresElement.attrib.get('copy') == '1':
sourceObject.copyFeatures = True
for glyphElement in sourceElement.findall(".glyph"):
glyphName = glyphElement.attrib.get('name')
if glyphName is None:
continue
if glyphElement.attrib.get('mute') == '1':
sourceObject.mutedGlyphNames.append(glyphName)
for kerningElement in sourceElement.findall(".kerning"):
if kerningElement.attrib.get('mute') == '1':
sourceObject.muteKerning = True
self.documentObject.sources.append(sourceObject)
def locationFromElement(self, element):
elementLocation = None
for locationElement in element.findall('.location'):
elementLocation = self.readLocationElement(locationElement)
break
return elementLocation
def readLocationElement(self, locationElement):
""" Format 0 location reader """
loc = {}
for dimensionElement in locationElement.findall(".dimension"):
dimName = dimensionElement.attrib.get("name")
if dimName not in self.axisDefaults:
continue
xValue = yValue = None
try:
xValue = dimensionElement.attrib.get('xvalue')
xValue = float(xValue)
except ValueError:
self.logger.info("KeyError in readLocation xValue %3.3f", xValue)
try:
yValue = dimensionElement.attrib.get('yvalue')
if yValue is not None:
yValue = float(yValue)
except ValueError:
pass
if yValue is not None:
loc[dimName] = (xValue, yValue)
else:
loc[dimName] = xValue
return loc
def readInstances(self, makeGlyphs=True, makeKerning=True, makeInfo=True):
instanceElements = self.root.findall('.instances/instance')
for instanceElement in self.root.findall('.instances/instance'):
self._readSingleInstanceElement(instanceElement, makeGlyphs=makeGlyphs, makeKerning=makeKerning, makeInfo=makeInfo)
def _readSingleInstanceElement(self, instanceElement, makeGlyphs=True, makeKerning=True, makeInfo=True):
filename = instanceElement.attrib.get('filename')
if filename is not None:
instancePath = os.path.join(os.path.dirname(self.documentObject.path), filename)
filenameTokenForResults = os.path.basename(filename)
else:
instancePath = None
instanceObject = self.instanceDescriptorClass()
instanceObject.path = instancePath
name = instanceElement.attrib.get("name")
if name is not None:
instanceObject.name = name
familyname = instanceElement.attrib.get('familyname')
if familyname is not None:
instanceObject.familyName = familyname
stylename = instanceElement.attrib.get('stylename')
if stylename is not None:
instanceObject.styleName = stylename
postScriptFontName = instanceElement.attrib.get('postscriptfontname')
if postScriptFontName is not None:
instanceObject.postScriptFontName = postScriptFontName
styleMapFamilyName = instanceElement.attrib.get('stylemapfamilyname')
if styleMapFamilyName is not None:
instanceObject.styleMapFamilyName = styleMapFamilyName
styleMapStyleName = instanceElement.attrib.get('stylemapstylename')
if styleMapStyleName is not None:
instanceObject.styleMapStyleName = styleMapStyleName
instanceLocation = self.locationFromElement(instanceElement)
if instanceLocation is not None:
instanceObject.location = instanceLocation
for glyphElement in instanceElement.findall('.glyphs/glyph'):
self.readGlyphElement(glyphElement, instanceObject)
for infoElement in instanceElement.findall("info"):
self.readInfoElement(infoElement, instanceObject)
self.documentObject.instances.append(instanceObject)
def readInfoElement(self, infoElement, instanceObject):
""" Read the info element.
::
<info/>
Let's drop support for a different location for the info. Never needed it.
"""
infoLocation = self.locationFromElement(infoElement)
instanceObject.info = True
def readKerningElement(self, kerningElement, instanceObject):
""" Read the kerning element.
::
Make kerning at the location and with the masters specified at the instance level.
<kerning/>
"""
kerningLocation = self.locationFromElement(kerningElement)
instanceObject.addKerning(kerningLocation)
def readGlyphElement(self, glyphElement, instanceObject):
"""
Read the glyph element.
::
<glyph name="b" unicode="0x62"/>
<glyph name="b"/>
<glyph name="b">
<master location="location-token-bbb" source="master-token-aaa2"/>
<master glyphname="b.alt1" location="location-token-ccc" source="master-token-aaa3"/>
<note>
This is an instance from an anisotropic interpolation.
</note>
</glyph>
"""
glyphData = {}
glyphName = glyphElement.attrib.get('name')
if glyphName is None:
raise DesignSpaceDocumentError("Glyph object without name attribute.")
mute = glyphElement.attrib.get("mute")
if mute == "1":
glyphData['mute'] = True
unicodeValue = glyphElement.attrib.get('unicode')
if unicodeValue is not None:
unicodeValue = int(unicodeValue, 16)
glyphData['unicodeValue'] = unicodeValue
note = None
for noteElement in glyphElement.findall('.note'):
glyphData['note'] = noteElement.text
break
instanceLocation = self.locationFromElement(glyphElement)
if instanceLocation is not None:
glyphData['instanceLocation'] = instanceLocation
glyphSources = None
for masterElement in glyphElement.findall('.masters/master'):
fontSourceName = masterElement.attrib.get('source')
sourceLocation = self.locationFromElement(masterElement)
masterGlyphName = masterElement.attrib.get('glyphname')
if masterGlyphName is None:
# if we don't read a glyphname, use the one we have
masterGlyphName = glyphName
d = dict( font=fontSourceName,
location=sourceLocation,
glyphName=masterGlyphName)
if glyphSources is None:
glyphSources = []
glyphSources.append(d)
if glyphSources is not None:
glyphData['masters'] = glyphSources
instanceObject.glyphs[glyphName] = glyphData
class DesignSpaceDocument(object):
""" Read, write data from the designspace file"""
def __init__(self, readerClass=None, writerClass=None):
self.path = None
self.formatVersion = None
self.sources = []
self.instances = []
self.axes = []
#
if readerClass is not None:
self.readerClass = readerClass
else:
self.readerClass = BaseDocReader
if writerClass is not None:
self.writerClass = writerClass
else:
self.writerClass = BaseDocWriter
def read(self, path):
self.path = path
reader = self.readerClass(path, self)
reader.read()
def write(self, path):
writer = self.writerClass(path, self)
writer.write()
def addSource(self, sourceDescriptor):
self.sources.append(sourceDescriptor)
def addInstance(self, instanceDescriptor):
self.instances.append(instanceDescriptor)
def addAxis(self, axisDescriptor):
self.axes.append(axisDescriptor)
def newDefaultLocation(self):
loc = {}
for axisDescriptor in self.axes:
loc[axisDescriptor.name] = axisDescriptor.default
return loc
if __name__ == "__main__":
def test():
u"""
>>> import os
>>> testDocPath = os.path.join(os.getcwd(), "test.designspace")
>>> masterPath1 = os.path.join(os.getcwd(), "masters", "masterTest1.ufo")
>>> masterPath2 = os.path.join(os.getcwd(), "masters", "masterTest2.ufo")
>>> instancePath1 = os.path.join(os.getcwd(), "instances", "instanceTest1.ufo")
>>> instancePath2 = os.path.join(os.getcwd(), "instances", "instanceTest2.ufo")
>>> doc = DesignSpaceDocument()
>>> # add master 1
>>> s1 = SourceDescriptor()
>>> s1.path = masterPath1
>>> s1.name = "master.ufo1"
>>> s1.copyLib = True
>>> s1.copyInfo = True
>>> s1.copyFeatures = True
>>> s1.location = dict(weight=0)
>>> s1.familyName = "MasterFamilyName"
>>> s1.styleName = "MasterStyleNameOne"
>>> s1.mutedGlyphNames.append("A")
>>> s1.mutedGlyphNames.append("Z")
>>> doc.addSource(s1)
>>> # add master 2
>>> s2 = SourceDescriptor()
>>> s2.path = masterPath2
>>> s2.name = "master.ufo2"
>>> s2.copyLib = False
>>> s2.copyInfo = False
>>> s2.copyFeatures = False
>>> s2.muteKerning = True
>>> s2.location = dict(weight=1000)
>>> s2.familyName = "MasterFamilyName"
>>> s2.styleName = "MasterStyleNameTwo"
>>> doc.addSource(s2)
>>> # add instance 1
>>> i1 = InstanceDescriptor()
>>> i1.path = instancePath1
>>> i1.familyName = "InstanceFamilyName"
>>> i1.styleName = "InstanceStyleName"
>>> i1.name = "instance.ufo1"
>>> i1.location = dict(weight=500, spooky=666) # this adds a dimension that is not defined.
>>> i1.postScriptFontName = "InstancePostscriptName"
>>> i1.styleMapFamilyName = "InstanceStyleMapFamilyName"
>>> i1.styleMapStyleName = "InstanceStyleMapStyleName"
>>> glyphData = dict(name="arrow", mute=True, unicode="0x123")
>>> i1.glyphs['arrow'] = glyphData
>>> doc.addInstance(i1)
>>> # add instance 2
>>> i2 = InstanceDescriptor()
>>> i2.path = instancePath2
>>> i2.familyName = "InstanceFamilyName"
>>> i2.styleName = "InstanceStyleName"
>>> i2.name = "instance.ufo2"
>>> # anisotropic location
>>> i2.location = dict(weight=500, width=(400,300))
>>> i2.postScriptFontName = "InstancePostscriptName"
>>> i2.styleMapFamilyName = "InstanceStyleMapFamilyName"
>>> i2.styleMapStyleName = "InstanceStyleMapStyleName"
>>> glyphMasters = [dict(font="master.ufo1", glyphName="BB", location=dict(width=20,weight=20)), dict(font="master.ufo2", glyphName="CC", location=dict(width=900,weight=900))]
>>> glyphData = dict(name="arrow", unicodeValue=1234)
>>> glyphData['masters'] = glyphMasters
>>> glyphData['note'] = "A note about this glyph"
>>> glyphData['instanceLocation'] = dict(width=100, weight=120)
>>> i2.glyphs['arrow'] = glyphData
>>> i2.glyphs['arrow2'] = dict(mute=False)
>>> doc.addInstance(i2)
>>> # write some axes
>>> a1 = AxisDescriptor()
>>> a1.minimum = 0
>>> a1.maximum = 1000
>>> a1.default = 0
>>> a1.name = "weight"
>>> a1.tag = "wght"
>>> a1.labelNames[u'fa-IR'] = u"قطر"
>>> a1.labelNames[u'en'] = u"Wéíght"
>>> doc.addAxis(a1)
>>> a2 = AxisDescriptor()
>>> a2.minimum = 0
>>> a2.maximum = 1000
>>> a2.default = 0
>>> a2.name = "width"
>>> a2.tag = "wdth"
>>> a2.map = [(0.0, 10.0), (401.0, 66.0), (1000.0, 990.0)]
>>> doc.addAxis(a2)
>>> # add an axis that is not part of any location to see if that works
>>> a3 = AxisDescriptor()
>>> a3.minimum = 333
>>> a3.maximum = 666
>>> a3.default = 444
>>> a3.name = "spooky"
>>> a3.tag = "spok"
>>> a3.map = [(0.0, 10.0), (401.0, 66.0), (1000.0, 990.0)]
>>> #doc.addAxis(a3) # uncomment this line to test the effects of default axes values
>>> # write the document
>>> doc.write(testDocPath)
>>> # import it again
>>> new = DesignSpaceDocument()
>>> new.read(testDocPath)
>>> for a, b in zip(doc.instances, new.instances):
... a.compare(b)
>>> for a, b in zip(doc.sources, new.sources):
... a.compare(b)
>>> for a, b in zip(doc.axes, new.axes):
... a.compare(b)
>>> [n.mutedGlyphNames for n in new.sources]
[['A', 'Z'], []]
"""
def _test():
import doctest
doctest.testmod()
print "done"
_test()

292
README.md Normal file
View File

@ -0,0 +1,292 @@
MutatorMath started out with its own reader and writer for designspaces. Since then the use of designspace has broadened and it would be useful to have a reader and writer that are independent of a specific system.
DesignSpaceDocument Object
===================
An object to read, write and edit interpolation systems for typefaces.
* Originally written for MutatorMath.
* Also used in fontTools.varlib.
* Define sources, axes and instances.
* Not all values might be required by all applications.
A couple of differences between things that use designspaces:
* Varlib does not support anisotropic interpolations.
* The goals of Varlib and MutatorMath are different, so not all attributes are always needed.
* FDK ?
The DesignSpaceDocument object can read and write .designspace data. It imports the axes, sources and instances to very basic "descriptor" objects that store the data in attributes. Data is added to the document by creating such descriptor objects, filling them with data and then adding them to the document. This makes it easy to integrate this object in different contexts.
The DesignSpaceDocument object can be subclassed to work with different objects, as long as they have the same attributes.
The object does not do any validation.
```python
from designspaceDocument import DesignSpaceDocument
doc = DesignSpaceDocument()
doc.read("some/path/to/my.designspace")
doc.axes
doc.sources
doc.instances
```
# Source descriptor object attributes
* `path`: string. Path to the source file. MutatorMath + Varlib.
* `name`: string. Unique identifier name of the source, used to identify it if it needs to be referenced from elsewhere in the document. MutatorMath.
* `location`: dict. Axis values for this source. MutatorMath + Varlib
* `copyLib`: bool. Indicates if the contents of the font.lib need to be copied to the instances. MutatorMath.
* `copyInfo` bool. Indicates if the non-interpolating font.info needs to be copied to the instances. MutatorMath.
* `copyGroups` bool. Indicates if the groups need to be copied to the instances. MutatorMath.
* `copyFeatures` bool. Indicates if the feature text needs to be copied to the instances. MutatorMath.
* `muteKerning`: bool. Indicates if the kerning data from this source needs to be muted (i.e. not be part of the calculations). MutatorMath.
* `muteInfo`: bool. Indicated if the interpolating font.info data for this source needs to be muted. MutatorMath.
* `mutedGlyphNames`: list. Glyphnames that need to be muted in the instances. MutatorMath.
* `familyName`: string. Family name of this source. Though this data can be extracted from the font, it can be efficient to have it right here. Varlib.
* `styleName`: string. Style name of this source. Though this data can be extracted from the font, it can be efficient to have it right here. Varlib.
```python
doc = DesignSpaceDocument()
s1 = SourceDescriptor()
s1.path = masterPath1
s1.name = "master.ufo1"
s1.copyLib = True
s1.copyInfo = True
s1.copyFeatures = True
s1.location = dict(weight=0)
s1.familyName = "MasterFamilyName"
s1.styleName = "MasterStyleNameOne"
s1.mutedGlyphNames.append("A")
s1.mutedGlyphNames.append("Z")
doc.addSource(s1)
```
# Instance descriptor object
* `path`: string. Path to the instance file, which may or may not exist. MutatorMath
* `name`: string. Unique identifier name of the instance, used to identify it if it needs to be referenced from elsewhere in the document.
* `location`: dict. Axis values for this source. MutatorMath + Varlib.
* `familyName`: string. Family name of this instance. MutatorMath + Varlib.
* `styleName`: string. Style name of this source. MutatorMath + Varlib.
* `postScriptFontName`: string. Postscript FontName for this instance. MutatorMath.
* `styleMapFamilyName`: string. StyleMap FamilyName for this instance. MutatorMath.
* `styleMapStyleName`: string. StyleMap StyleName for this instance. MutatorMath.
* `glyphs`: dict for special master definitions for glyphs. If glyphs need special masters (to record the results of executed rules for example). MutatorMath.
* `kerning`: bool. Indicates if this instance needs its kerning calculated. MutatorMath.
* `info`: bool. Indicated if this instance needs the interpolating font.info calculated.
```python
i2 = InstanceDescriptor()
i2.path = instancePath2
i2.familyName = "InstanceFamilyName"
i2.styleName = "InstanceStyleName"
i2.name = "instance.ufo2"
# anisotropic location
i2.location = dict(weight=500, width=(400,300))
i2.postScriptFontName = "InstancePostscriptName"
i2.styleMapFamilyName = "InstanceStyleMapFamilyName"
i2.styleMapStyleName = "InstanceStyleMapStyleName"
glyphMasters = [dict(font="master.ufo1", glyphName="BB", location=dict(width=20,weight=20)), dict(font="master.ufo2", glyphName="CC", location=dict(width=900,weight=900))]
glyphData = dict(name="arrow", unicodeValue=1234)
glyphData['masters'] = glyphMasters
glyphData['note'] = "A note about this glyph"
glyphData['instanceLocation'] = dict(width=100, weight=120)
i2.glyphs['arrow'] = glyphData
i2.glyphs['arrow2'] = dict(mute=False)
doc.addInstance(i2)
```
# Axis descriptor object
* `tag`: string. Four letter tag for this axis. Some might be registered at the OpenType specification.
* `name`: string. Name of the axis as it is used in the location dicts. MutatorMath + Varlib.
* `labelNames`: dict. When defining a non-registered axis, it will be necessary to define user-facing readable names for the axis. Keyed by xml:lang code. Varlib.
* `minimum`: number. The minimum value for this axis. MutatorMath + Varlib.
* `maximum`: number. The maximum value for this axis. MutatorMath + Varlib.
* `default`: number. The default value for this axis, i.e. when a new location is created, this is the value this axis will get. MutatorMath + Varlib.
* `map`: list of input / output values that can describe a warp of user space to designspace coordinates. If no map values are present, it is assumed it is [(minimum, minimum), (maximum, maximum)].laat iklaa Varlib.
```python
a1 = AxisDescriptor()
a1.minimum = 0
a1.maximum = 1000
a1.default = 0
a1.name = "weight"
a1.tag = "wght"
a1.labelNames[u'fa-IR'] = u"قطر"
a1.labelNames[u'en'] = u"Wéíght"
a1.map = [(0.0, 10.0), (401.0, 66.0), (1000.0, 990.0)]
```
# Document xml structure
* The `axes` element contains one or more `axis` elements.
* The `sources` element contains one or more `source` elements.
* The `instances` element contains one or more `instance` elements.
```xml
<?xml version='1.0' encoding='utf-8'?>
<designspace format="3">
<axes>
<!-- define axes here -->
<axis../>
</axes>
<sources>
<!-- define masters here -->
<source../>
</sources>
<instances>
<!-- define instances here -->
<instance../>
</instances>
</designspace>
```
# 1. `axis` element
* Define a single axis
* Child element of `axes`
### Attributes
* `name`: required, string. Name of the axis that is used in the location elements.
* `tag`: required, string, 4 letters. Some axis tags are registered in the OpenType Specification.
* `minimum`: required, number. The minimum value for this axis.
* `maximum`: required, number. The maximum value for this axis.
* `default`: required, number. The default value for this axis.
```xml
<axis name="weight" tag="wght" minimum="-1000" maximum="1000 default="0">
```
# 1.1 `labelname` element
* Defines a human readable name for UI use.
* Optional for non-registered axis names.
* Can be localised with `xml:lang`
* Child element of `axis`
### Attributes
* `xml:lang`: required, string. [XML language definition](https://www.w3.org/International/questions/qa-when-xmllang.en)
### Value
* The natural language name of this axis.
```xml
<labelName xml:lang="fa-IR">قطر</labelName>
<labelName xml:lang="en">Wéíght</labelName>
```
# 1.2 `map` element
* Defines a single node in a series of input value / output value pairs.
* Together these values transform the designspace.
* Child of `axis` element.
```xml
<map input="0.0" output="10.0" />
<map input="401.0" output="66.0" />
<map input="1000.0" output="990.0" />
```
# 2. `source` element
* Defines a single font that contributes to the designspace.
* Child element of `sources`
### Attributes
* `familyname`: optional, string. The family name of the source font. While this could be extracted from the font data itself, it can be more efficient to add it here.
* `stylename`: optional, string. The style name of the source font.
* `name`: required, string. A unique name that can be used to identify this font if it needs to be referenced elsewhere.
* `filename`: required, string. A path to the source file, relative to the root path of this document. The path can be at the same level as the document or lower.
# 2.1 `lib` element
* `<lib copy="1" />`
* Child element of `source`
* Defines if the instances can inherit the data in the lib of this source.
* MutatorMath only
# 2.2 `info` element
* `<info copy="1" />`
* Child element of `source`
* Defines if the instances can inherit the non-interpolating font info from this source.
* MutatorMath only
# 2.3 `features` element
* `<features copy="1" />`
* Defines if the instances can inherit opentype feature text from this source.
* Child element of `source`
* MutatorMath only
# 2.4 `glyph` element
* Can appear in `source` as well as in `instance` elements.
* In a `source` element this states if a glyph is to be excluded from the calculation.
* MutatorMath only
### Attributes
* `<glyph mute="1" name="A"/>`
* `mute`: optional, number, andts
# 2.5.1`dimension` element
* Child element of `location`
### Attributes
* `name`: required, string. Name of the axis.
* `xvalue`: required, number. The value on this axis.
* `yvalue`: optional, number. Separate value for anisotropic interpolations.
# Example
```xml
<source familyname="MasterFamilyName" filename="masters/masterTest1.ufo" name="master.ufo1" stylename="MasterStyleNameOne">
<lib copy="1" />
<features copy="1" />
<info copy="1" />
<glyph mute="1" name="A" />
<glyph mute="1" name="Z" />
<location>
<dimension name="width" xvalue="0.000000" />
<dimension name="weight" xvalue="0.000000" />
</location>
</source>
```
# 3. `instance` element
* Defines a single font that can be calculated with the designspace.
* Child element of `instances`
* For use in Varlib the instance element really only needs the names and the location. The `glyphs` element is not required.
* MutatorMath uses the `glyphs` element to describe how certain glyphs need different masters, mainly to describe the effects of conditional rules in Superpolator.
### Attributes
* `familyname`: required, string. The family name of the instance font. Corresponds with `font.info.familyName`
* `stylename`: required, string. The style name of the instance font. Corresponds with `font.info.styleName`
* `name`: required, string. A unique name that can be used to identify this font if it needs to be referenced elsewhere.
* `filename`: string. Required for MutatorMath. A path to the instance file, relative to the root path of this document. The path can be at the same level as the document or lower.
* `postscriptfontname`: string. Optional for MutatorMath. Corresponds with `font.info.postscriptFontName`
* `stylemapfamilyname`: string. Optional for MutatorMath. Corresponds with `styleMapFamilyName`
* `stylemapstylename `: string. Optional for MutatorMath. Corresponds with `styleMapStyleName`
```xml
<instance familyname="InstanceFamilyName" filename="instances/instanceTest2.ufo" name="instance.ufo2" postscriptfontname="InstancePostscriptName" stylemapfamilyname="InstanceStyleMapFamilyName" stylemapstylename="InstanceStyleMapStyleName" stylename="InstanceStyleName">
<location>
<dimension name="width" xvalue="400" yvalue="300" />
<dimension name="weight" xvalue="500" />
</location>
<glyphs>
<glyph name="arrow2" />
<glyph name="arrow" unicode="0x4d2">
<location>
<dimension name="width" xvalue="100" />
<dimension name="weight" xvalue="120" />
</location>
<note>A note about this glyph</note>
<masters>
<master glyphname="BB" source="master.ufo1">
<location>
<dimension name="width" xvalue="20" />
<dimension name="weight" xvalue="20" />
</location>
</master>
</masters>
</glyph>
</glyphs>
<kerning />
<info />
</instance>
```
## Notes on this document
Second version. The package is rather new and changes are to be expected.

0
requirements.txt Normal file
View File

16
setup.py Normal file
View File

@ -0,0 +1,16 @@
#!/usr/bin/env python
from setuptools import setup
setup(name = "DesignSpaceDocument",
version = "0.1",
description = "Python object to read, write and edit MutatorMath designspace data.",
author = "Erik van Blokland",
author_email = "erik@letterror.com",
url = "https://github.com/LettError/designSpaceDocument",
license = "MIT",
packages = [
"designSpaceDocument",
],
package_dir = {"":"Lib"},
)