Data Structures
Colour
Unsuprisingly, the Colour objects represent a specific colour for use in the printing process. These allow for both RGB and CMYK colours to be represented. MOO prints in CMYK, but Little MOO will automatically translate RGB colours into CMYK colours for printing.
CMYK + RGB are 2 different methods of representing colour. RGB is the colour system used in TVs and computer monitors, where different coloured light is added together to produce the desired colour. Printing in CMYK involves starting with a white piece of paper, and then printing varying amounts of Cyan, Magenta, Yellow and Black onto the paper to produce the desired colour. Confusingly, CMYK is known as a subtractive model (because you start with white, and adding more ink brings the printed colour closer to black).
One issue with the physical printing is that because you've always got the underlying white colour, there will be some colours possible to generate in RGB, which cannot be translated into CMYK well. Bright Pink and Royal Blue (and indeed anything which could be considered a little fluorescent) are good examples of where the RGB colour can't be printed onto white paper with true reproduction.
Conversely, the fact that CMYK explicitly includes Black ink (the K component), this means that there isn't one "black" colour - 0,0,0,100 is known as "Process Black" and uses on the black ink, but darker blacks can be printed by adding some of the other inks as well (e.g. 30, 30, 30, 100), and by varying the amounts, tints in the black can be created. This causes a problem in displaying a CMYK print definition on an RGB screen - if CMYK 0, 0, 0, 100 translated to #000000, then how would you show that CMYK 30, 30, 30, 100 is a darker black? Generally, this is done by setting CMYK 0, 0, 0, 100 to a shade of gray (e.g. #303030). The effect is that on-screen, your black might appear a bit gray.
So why not use rich black for everything? In theory, (and on screen) this should work fine, but physically reality poses new problems here. The C, Y, M, and K inks get printed by plates, and the plates cannot line up perfectly with each other (due to the way the paper absorbs the ink - try looking at any printed product under a high resolution eye-glass to see what actually happens), which means that the C, M and Y may drift slightly off the edge of the box defined to be "black". This means that you'd see some colour where you didn't want any.
To ensure that your customers receive the best quality product that they can we have the following recommendations:
- If the black colour is for foreground text, or as a background to white text, don't use rich blacks, but only the process black. Trust us - it will still be black.
- Try not to use colours which might be described as fluorescent. These won't print well.
Definition
The Colour model has the following properties
- "type" - One of "RGB" or "CMYK" to denote the type of colour being represented. Either type of colour can be used in any situation (but bear in the mind the recommendations above)
- For RGB:
- "r" (JSON), "Red" (XML) - the red component of the colour. Integer, 0 <= r <= 255
- "g" (JSON), "Green" (XML) - the green component of the colour. Integer, 0 <= r <= 255
- "b" (JSON), "Blue" (XML) - the blue component of the colour. Integer, 0 <= r <= 255
- For CMYK:
- "c" (JSON), "Cyan" (XML) - the cyan ink component of the colour. Float 0.0 <= c <= 100.0
- "m" (JSON), "Magenta" (XML) - the magenta ink component of the colour. Float 0.0 <= c <= 100.0
- "y" (JSON), "Yellow" (XML) - the yellow ink component of the colour. Float 0.0 <= c <= 100.0
- "k" (JSON), "Black" (XML) - the black ink component of the colour. Float 0.0 <= c <= 100.0
Example
XML
<Colour type="CMYK">
<Cyan>52.3</Cyan>
<Magenta>49.2</Magenta>
<Yellow>100.0</Yellow>
<Black>0</Black>
</Colour>
JSON
"colour":{
"type":"RGB",
"r": 255,
"g": 0,
"b": 0
}
Font
The Font type describes the specific font and style that should be used to render a piece of text. A Font definition applies to an entire text line. We don't currently support embedded styling within a Text or MultiLineText item. For the moment, while we do have a setting for italicising text, it's not supported yet.
One point of note is the template setting "FontSubstitutionStrategy" which defines what happens when rendering text on a Side for printing, if some of the characters used in a text line cannot be found in the font family specified. Currently, only the Arial font has support for (almost!) all character sets from around the world. As a result, if you ask to print Japanese characters in, say, AvantGarde, we probably won't have those characters in that font. In this case, we'd to take some action in order to print the pack of cards. Note that you cannot override this setting in the Pack data you provide, but to explain what will happen, the possible strategies that we employ are:
- allLinesIfAnyNeeded - this means that if any single line of text contains characters which cannot be printed with the specified font, then ALL text lines on that Side will be changed to the Arial font in order to provide deterministic behaviour (and ensure the best chance of using a font which will contain the requested characters)
- lineByLine - this means that if a single line of text contains characters which cannot be printed with the specified font, then ONLY those text lines affected will have their fonts changed.
- none - no action will be taken. This likely means that the characters will not be printed at all.
For templates available through the API, you will almost always see "allLinesIfAnyNeeded" as the strategy, so that in the event that characters can't be printed with the selected font, we will still print the characters, but in Arial rather than the selected font.
Definition
The Font type has the following members:
- "family" - the font family name. MUST be one of:
- arial
- avantgarde
- bryant
- courier
- frutigerltpro
- georgia
- helv
- helvetica
- index
- meta
- officina
- radio
- router
- vagrounded
- "bold" - boolean - whether the type should be bold or not
- "italic" - boolean - whether the type should be italic or not. MUST be "false" for the moment.
Example
XML
<Font>
<Family>helvetica</Family>
<Bold>false</Bold>
<Italic>false</Italic>
</Font>
JSON
"font":{
"fontFamily":"helvetica",
"bold":true,
"italic":false
},
Bounding Box
The Bounding Box is an frequently-used type within the API. It's used to define anything that is a 2-D rectangular object within the MOO system. Specifically, this includes the clipping boxes for text + image items (where content will be cut-off if it overflows the box), and image boxes (describing where an image should be placed underneath an image clipping box).
We have perhaps moved away from the traditional method of top-left/width/height that you'd find, for instance, in the DOM / CSS box model, instead opting for the "centre" point as the positional anchor point. This is so that each action taken on a box is represented by a change to a single property set. Moving the image changes just the center point, zooming changes only the width/height, and rotation changes only the angle. Moreover, the notion of a "top-left" point becomes rather more complicated to understand if you specify the box should rotate by say 90 or 180 degrees - would the top-left be the one before or after rotation? There are other similar problematic questions to answer under rotation, and therefore we describe the final position of the box as:
- The center of the box is placed at the center point
- The width + height of the box are before rotation
- We rotate this box about the centre point to arrive at the final point
In this way, even under any rotation, moving the box just changes the center point. Zooming only changes the width + height (and is irrelevant of rotation), and the angle defines the final rotation of the box.
Definition
The Bounding Box type defines the following properties:
- "center" - defines the center point, and has the following sub-properties
- "x" - Float. The X position in the same units as the template (usually represented in millimeters), from the top-left corner of the template Print Area
- "y" - Float. The Y position in the same units as the template (usually represented in millimeters), from the top-left corner of the template Print Area. Note that our system works in a top-down co-ordinate system, so positive Y means moving down the card from the top.
- "width" - Float. Defines the width of the box in the same units as the template (usually millimeters)
- "height" - Float. Defines the height of the box in the same units as the template (usually millimeters)
- "angle" - Float. The angle of rotation of the box in degrees.
Example
XML
<ClippingBox>
<Centre x="16" y="29.5"/>
<Width>32</Width>
<Height>59</Height>
<Angle>0</Angle>
</ClippingBox>
JSON
"imageBox":{
"center":{
"x":36.845814978,
"y":14.9347826087
},
"width":74,
"height":49.5480501393,
"angle":0
},
Offriamo opzioni di spedizione e stampa ultraveloci se vuoi ricevere l'ordine il prima possibile!
Servizi aziendali MOO offre una procedura d'ordine semplice per aziende con più di 10 dipendenti
Non siamo contenti finché tu non sei contento. Il nostro servizio clienti è sempre a tua disposizione
