Mapping Coordinates from Spreadshirt’s SVG User Coordinate System to your Application’s Coordinate System (API Terminology Explained #10)

In this blog post, I will tell you how to translate product type, product, design and text coordinates correctly from Spreadshirt’s SVG user coordinate system to your application’s coordinate system. You need to understand how the translation works in case you want to display and manipulate Spreadshirt products in your own applications. Please read the Text and Design Positioning Guide to learn more about how to position text and designs on Spreadshirt products. Also read Product Model, ProductType Model, Design Model to learn more about them in case you don’t know already.

Preliminaries

When displaying a Spreadshirt product or creating a new one in your own application, you need to consider different coordinates and sizes from Spreadshirt product types, products, designs and text. The coordinates and sizes to be considered are as follows:

ProductType

  • View size – size of the view, e.g. front, back or left side on a shirt
  • ViewMap offset – position of the print area on the actual view
  • PrintArea size – size of the print area we can print on

Product

  • Configuration offset – position of the actual configuration on the print area

Design

  • Size – actual size of the design

Text

  • Position – start position of the text depending on the given text anchor
  • Font size – size of the font used for the text
  • Text anchor – alignment of the text, e.g. left, center, right

Spreadshirt does all internal calculations in Spreadshirt’s SVG user coordinate system in millimeters right now. That means all coordinates, sizes and font sizes are provided in millimeters! So when displaying a Spreadshirt product in a Web browser or creating a new one, you always need to translate the millimeter coordinates, sizes and font sizes to pixels and vice versa.

Translation

So, let’s assume we want to render the following product with a text and a design on it.

The XML for that product would be:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<product xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns="http://api.spreadshirt.net"
         weight="0.0"
         xlink:href="http://api.spreadshirt.net/api/v1/shops/205909/products/200001504"
         id="200001504">
    <name>Männer Basis-T-Shirt</name>
    <user xlink:href="http://api.spreadshirt.net/api/v1/users/40000" id="40000"/>
    <productType xlink:href="http://api.spreadshirt.net/api/v1/shops/205909/productTypes/6" id="6"/>
    <appearance id="1"/>
    <restrictions>
        <freeColorSelection>false</freeColorSelection>
        <example>false</example>

        <softBoundarySupported>true</softBoundarySupported>
    </restrictions>
    <configurations>
        <configuration type="design" id="200001557">
            <printArea id="4"/>
            <printType xlink:href="http://api.spreadshirt.net/api/v1/shops/205909/printTypes/2" id="2"/>
            <offset unit="mm">
                <x>237.06</x>

                <y>184.39</y>
            </offset>
            <content dpi="25.4" unit="mm">
                <svg viewBox="0 0 39.79 39.79">
                    <image xlink:href="http://api.spreadshirt.net/image-server/v1/designs/4868344,
                                       colors[0]=008751"
                           transform="" height="39.79" width="39.79"
                           printColorRGBs="#008751" printColorIds="6" designId="4868344"/>
                </svg>
            </content>
            <designs>

                <design xlink:href="http://api.spreadshirt.net/api/v1/shops/205909/designs/m4868344-1"
                        id="4868344"/>
            </designs>
            <restrictions>
                <changeable>false</changeable>
            </restrictions>
            <resources>
                <resource xlink:href="http://api.spreadshirt.net/image-server/v1/configurations/200001557"
                          mediaType="png"/>
            </resources>

        </configuration>
        <configuration type="text" id="200001558">
            <printArea id="4"/>
            <printType xlink:href="http://api.spreadshirt.net/api/v1/shops/205909/printTypes/2" id="2"/>
            <offset unit="mm">
                <x>0.0</x>
                <y>0.0</y>
            </offset>

            <content dpi="25.4" unit="mm">
                <svg viewBox="34.911 105.584 239.76 69.87">
                    <text height="69.87" width="239.76" transform="" font-style="normal" font-size="25"
                          font-weight="normal" font-family="AnzeigenGroteskLT" fill="#000000"
                          text-anchor="start" y="122.94192792604005" x="34.911085583526095"
                          printColorId="2" fontId="109" fontFamilyId="50">
                        <tspan transform="" font-style="normal" font-size="25"
                               font-weight="normal" font-family="AnzeigenGroteskLT" fill="#000000"
                               text-anchor="start" y="122.94192792604005" x="34.911085583526095"
                               printColorId="2" fontId="109"
                               fontFamilyId="50">Workers building emergency</tspan>
                        <tspan transform="" font-style="normal" font-size="25"
                               font-weight="normal" font-family="AnzeigenGroteskLT" fill="#000000"
                               text-anchor="start" y="147.94192792604005" x="34.911085583526095"
                               printColorId="2" fontId="109"
                               fontFamilyId="50">dams to stem second toxic</tspan>
                        <tspan transform="" font-style="normal" font-size="25"
                               font-weight="normal" font-family="AnzeigenGroteskLT" fill="#000000"
                               text-anchor="start" y="172.94192792604005" x="34.911085583526095"
                               printColorId="2" fontId="109"
                               fontFamilyId="50">spill</tspan>
                    </text>

                </svg>
            </content>
            <fontFamilies>
                <fontFamily xlink:href="http://api.spreadshirt.net/api/v1/shops/205909/fontFamilies/50"
                            id="50"/>
            </fontFamilies>
            <restrictions>
                <changeable>false</changeable>
            </restrictions>

            <resources>
                <resource xlink:href="http://api.spreadshirt.net/image-server/v1/configurations/200001558"
                          mediaType="png"/>
            </resources>
        </configuration>
    </configurations>
    <resources>
        <resource xlink:href="http://api.spreadshirt.net/image-server/v1/products/200001504/views/1"
                  type="preview" mediaType="png"/>
        <resource xlink:href="http://api.spreadshirt.net/image-server/v1/products/200001504/views/1"
                  type="product" mediaType="png"/>
        <resource xlink:href="http://api.spreadshirt.net/image-server/v1/compositions/200001504/views/1"
                  type="composition" mediaType="png"/>
    </resources>
</product>

View Translation

As you can see, we use product type 6. Design and text are added to print area 4. So we have the following View, ViewMap and PrintArea values:

viewWidth = 686,486 mm
viewHeight = 686,486 mm
viewMapX = 191,236 mm
viewMapY = 68,648 mm
printAreaWidth = 308,918 mm
printAreaHeight = 566,351 mm

Now, in our example, we want to display the product in an HTML div of 500px x 500px. So, we first need to establish a view scale factor and then we need to translate all values with the view scale. The translation calculation would be as follows:

displayViewWidth = 500 px
viewScale = displayViewWidth/viewWidth = 500 px / 686,486 mm = 0,728 px/mm
displayViewMapX = viewMapX * viewScale = 191,236 mm * 0,728 px/mm = 139,277 px
displayViewMapY = viewMapY * viewScale = 68,648 mm * 0,728 px/mm = 49,996 px
displayPrintAreaWidth = printAreaWidth * viewScale = 308,918 mm * 0,728 px/mm = 224,985 px
displayPrintAreaHeight = printAreaHeight * viewScale = 566,351 mm * 0,728 px/mm = 412,473 px

Design Translation

To position the design correctly, we need to translate design configuration offset and design size values. As you can see, we used design 4868344. The translation calculation is as follows:

designConfigurationOffsetX = 237,06 mm
designConfigurationOffsetY = 184,39 mm
designSizeWidth = 39,79 mm
designSizeHeight = 39,79 mm

displayDesignConfigurationOffsetX = designConfigurationOffsetX * viewScale = 237.06 mm * 0,728 px/mm = 172,65 px
displayDesignConfigurationOffsetY = designConfigurationOffsetY * viewScale = 184,39 mm * 0,728 px/mm = 134,29 px
displayDesignSizeWidth = designSizeWidth * viewScale = 39,79 mm * 0,728 px/mm = 28,979 px
displayDesignSizeHeight = designSizeHeight * viewScale = 39,79 mm * 0,728 px/mm = 28,979 px

Text Translation

To position the text correctly, we need to translate the x, y and font size values of the text line “Workers building emergency …” correctly. Please note that this is the calculation for textAnchor start and for font Anzeigen. The translation calculation would be as follows:

textLineX = 34,911 mm
textLineY = 122,941 mm
fontSize = 25 mm

displayTextLineX = textLineX * viewScale = 34,911 mm * 0,728 px/mm = 25,425 px
displayTextLineY = textLineY * viewScale = 122,941 mm * 0,728 px/mm = 89,53 px
displayFontSize = fontSize * viewScale = 25 mm * 0,728 px/mm = 18,207 px

# font ascent and descent values for font Anzeigen are as follows
ascent = 288
descent = 72
baseline = displayFontSize * (ascent/(ascent+descent)) = 18,207 px * (288 / (288 + 72)) = 14,566 px

displayTextLineBaseLine = displayTextLineX + baseline = 25,425 px + 14,566 px = 40 px

The calculation above works well for displaying products in Web browsers. The opposite calculation has to be conducted when creating new products based on what is rendered in the browser. For a good example of how to do it in practice, please have a look at the Simplomat (Simple Shirt Designer) source code.

Summary

In this blog post, I told you how to translate product type, product, design and text coordinates correctly from Spreadshirt’s SVG user coordinate system to your application’s coordinate system. With this knowledge you are able to display and manipulate Spreadshirt products in your own applications.

Please also have a look at the other articles in the series “API Terminology Explained”:

——————————-
Martin Breest
Platform Evangelist

2 Replies to “Mapping Coordinates from Spreadshirt’s SVG User Coordinate System to your Application’s Coordinate System (API Terminology Explained #10)”

Comments are closed.