Parameters for all requests
- companyid - The companyid is a unique code that is given as part of your subscription to access the API. This code must be supplied as part of the header for each API request.
Refer to the Documentation page for each specific request and the supported Parameters
Lettering
Description
Lettering is generated by using the "Lettering" option. The lettering option is added after the
action. Lettering parameters are added after a ? character which is appended to Lettering.
For example: /api/Lettering/Render?Text=ABC
Parameters
-
Type - Type of lettering to generate. Valid values are:
- ltNormal - Straight text
- ltMonogram - Three-letter monograms
- ltArc - Text that follows the path of an arc
- ltCircle - 2 lines of text that follow the path of a circle
Default is "ltNormal".
- Text - Text to generate. The parameter 'Text' is required for all Lettering requests.
-
Font - Font to use to generate the lettering. Default is "Block New".
See list of available fonts.
- Height - Height of the text. Units are embroidery points. Default is "254".
- WidthCompression - Width compression of the text. Units are in percent. Default is "100" for 100%.
-
Justification - Justification of the text. Valid values are:
- jtCenter
- jtLeft
- jtRight
- jtFillBox
- jtFitToCurve
- jtFitToCurve will only work when the X3 and Y3 values are specified to create a curve
- See additional parameters below and Example 3 at the bottom of the page
Default is jtCenter.
-
Envelope - Envelope of the text. Valid values are:
- etRectangle
- etBridgeConcaveTop
- etBridgeConcaveBottom
- etDoubleConcaveBridges
- etBridgeConvexTop
- etBridgeConvexBottom
- etDoubleConvexBridges
- etConcaveTopConvexBottom
- etConvexTopConcaveBottom
- etPennantRight
- etPennantLeft
Default is etRectangle.
- Decoration - Decoration character to use. Valid only when Type="Monogram"
- Needle - Primary needle of the generated text. Needle is 0-based. Default is "0".
-
Recipe - Recipe to use when generating the text. Default is "Normal".
See list of available recipes.
- Recipe Note: See render or generate which will apply a recipe on top of any existing
-
MachineFormat - Machine format to use when generating the text. Default is "Tajima".
See list of available machine formats.
- X1 - X-value of the first point of the baseline.
- Y1 - Y-value of the first point of the baseline.
- X2 - X-value of the second point of the baseline.
- Y2 - Y-value of the second point of the baseline.
- X3 - X-value of the third point of the baseline for ltArc type and jtFitToCurve justification only.
- Y3 - Y-value of the third point of the baseline for ltArc type and jtFitToCurve justification only.
-
Palette[] - Array of palette colours. Values are RGB sextuplets (eg. ff0000 is red).
See arrays for more information about specifying array values.
- IsRainbowText
- true or false. Default is false
- The Rainbow text feature is a way to instantly create multi-colored text in a design. The Rainbow text inserts a color change at the end of each letter in the selected text, and the next color is chosen randomly from the threads in the active palette
- IsRainbowText Note: Do not combine IsRainbowText with a design-level Needles[] (Compounds, Templates) to recolour individual letters. The randomiser may give two neighbouring letters the same needle, which merges their colour blocks and shifts every Needles[] entry one position out. The supported route to per-letter needles is LetterNeedles[].
- RainbowColors - Array of rainbow color values.
- RainbowColors can only be set if the parameter IsRainbowText is set to true
- For each of the RainbowColors, there are 2 parameters that have be specified and 2 parameters that are required but conditional on each other:
- Name - The Name of the Thread Color to be set for the first color of the text
- Code - The Code of the Thread Color to be set for the first color of the text
- RGB - The Red, Green and Blue value of the Thread Color. Format is: 000,111,222. This is required only if the Hex parameter is not set
- Hex - The Hex value of the color that will be converted to an RGB value. Format is below. 6 characters in length. This is required only if the RGB parameter is not set
- Hexadecimal uses sixteen distinct symbols, in the case of css color the symbols 0–9 to represent values zero to nine (obviously), and A, B, C, D, E, F to represent values ten to fifteen. So, using one Hexadecimal character you can represent 16 values. With two Hexadecimal you can represent 256 (16*16) values.
- In RGB you have colours represented by Red Green Blue (R=0-255, G=0-255, B=0-255), so we use 3 pairs of Hexadecimal symbols! So when you see an RGB color, you can make the calculation below.
- Example:
- Hex: #4C8ED5 is RGB: 76, 142, 213.
- Because 4C = 76(Red), 8E = 142(Green), D5 = 213(Blue)
- RemoveUnusedNeedles - True/False value whether or not to remove unused needles from the design. Default is false. Cannot be combined with LetterNeedles[] or BottomLetterNeedles[] (see below).
-
LetterNeedles[] - Array of needle indices, one per character of Text, in order. Values are 0-based indexes into the design's palette - the same numbering as Needle.
See arrays for more information about specifying array values.
- The only bound is the palette supplied with the request: any palette index is valid, including needles above 15 and needles below the element needle. Values outside the palette are rejected (HTTP 400) naming the position, the value and the palette size.
- An empty entry (LetterNeedles[1]=) is an unset letter, and an array shorter than the text leaves the remaining letters unset. Unset letters follow UnsetLetterNeedles.
- Entries beyond the number of characters are dropped; GetInfo reports how many.
- Control sequences in the text are not characters and take no entry.
- A needle names a head, not a colour: changing the palette afterwards recolours the needle without reassigning the letters, so the same thread can appear on two heads.
- The assignment is stored in the design's outlines, after the element needle. Setting a text element's needle clears any per-letter assignment on it, including when it is set to the value it already had.
- Cannot be combined with RemoveUnusedNeedles=true (HTTP 400): removing unused needles renumbers the palette without carrying the assignment across.
- Absent or empty means no per-letter assignment; existing requests are unaffected.
- BottomLetterNeedles[] - The same as LetterNeedles[], for the bottom row (BottomText) when Type is ltCircle; LetterNeedles[] then addresses the top row (Text). The two rows are independently sized. Ignored, and reported as ignored in GetInfo, for lettering with a single row.
-
UnsetLetterNeedles - What happens to letters the arrays do not name. Has no effect unless LetterNeedles[] or BottomLetterNeedles[] is present.
- ulnElementNeedle - Unset letters go on the element needle and the rainbow randomiser is skipped, so the result is deterministic. If IsRainbowText is also set it is superseded and GetInfo reports it. Default.
- ulnRainbow - Requires IsRainbowText=true (HTTP 400 otherwise). The rainbow pass runs first and the named letters overwrite it, so unset letters are randomly assigned - non-deterministic, with the same colour-block behaviour rainbow text has today. Named letters are unaffected. If every letter is named the rainbow pass is skipped and GetInfo reports it.
- When the Type is ltCircle
- CenterX - X-value of the first point of the circle.
- CenterY - Y-value of the first point of the circle.
- RefX - X-value of the first point of the baseline from the X-value of the circle.
- RefY - Y-value of the first point of the baseline from the Y-value of the circle.
- See example 4 below
-
IsColoreel
- true or false. Default is false
- The Coloreel feature applies Coloreel effects such as gradient and repeating pattern to a text segment and designs
- ColoreelLibrary: The name of the Coloreel Library configured in DG. Required.
- ColoreelEffectName: Name of the effect configured in the Coloreel Library. Required.
Compounds can have their Start/Stop points specified.
See start/stop parameters.
Lettering can be transformed.
See transformation parameters.
Example 1
/api/Lettering/Render?Text=Pulse&ImageWidth=400&Palette[0]=ff0000
Example 2
/api/Lettering?Text=ABC&Type=ltMonogram&Decoration=*&Font=Monogram 1
Example 3
/api/Lettering/Render?Text=Pulse Micro&Type=ltArc&ImageWidth=1000&X1=-1000&Y1=0&X2=0&Y2=150&X3=1000&Y3=0&Justification=jtCenter&Palette[0]=ff0000
Example 4
/api/Lettering/Render?Text=Pulse Micro&BottomText=Pulse Micro&Type=ltCircle&ImageWidth=500&CenterX=0&CenterY=0&RefX=0&RefY=-700&Justification=jtCenter&Palette[0]=ff0000
Example 5
/api/Lettering/Render?Text=Pulse&ImageWidth=400&IsColoreel=true&ColoreelLibrary=Coloreel%20Medium&ColoreelEffectName=%23FF4B4B