Automated Computed Embroidery

Note for ACE clients: The thread cone requests belong to the ZSK Web API. They use the same StitchJob endpoint and the same WebApiLicense as your ACE jobs, but you must send them without "Client": "ACE". With it, the request is handled as an ACE picture/vector job and rejected with HTTP 400. Use the series ids from GetThreadConeSeries as ThreadTable in ACEParaOptimize. The same description is also available in the ZSK Web API documentation: GetThreadConeList.

Returns the thread weight and the full color list of one thread cone series (thread chart).

This is the third step of the thread cone lookup chain: GetThreadConeManufacturer → GetThreadConeSeries → GetThreadConeList (all colors of a series) or GetThreadCone (one color by its color number).

Send the request as JSON with POST to https://<ZSKAddress>/StitchJob. Pick the series with ThreadCone.ConeSeries. Use an id exactly as GetThreadConeSeries returns it, for example Amann-Isacord 40. Series ids have no fixed pattern (for example Madeira-FIRE FIGHTER or Candle Polyester Shade), so don't build them from the manufacturer name and the weight.

Response

The request returns a JobResponseType. When it succeeds, Success is true and RequestData holds a JSON object as a string (indented JSON text), so you have to parse RequestData a second time. ServerVersion.Major is the ServerVersion from the request. All other fields are empty strings.

Response (formatted for readability and shortened to the first two colors; the full Amann-Isacord 40 list has 391 colors):

{
  "Info": "",
  "NeedleColor": "",
  "NeedleSequence": "",
  "PreviewData": "",
  "RequestData": "{\u000d\u000a  \"Weight\": 40,\u000d\u000a  \"Colors\": [\u000d\u000a    {\u000d\u000a      \"Index\": 0,\u000d\u000a      \"ColorNumber\": \"3\",\u000d\u000a      \"R\": 235,\u000d\u000a      \"G\": 236,\u000d\u000a      \"B\": 238,\u000d\u000a      \"ColorName\": \"Ghost White\"\u000d\u000a    },\u000d\u000a    {\u000d\u000a      \"Index\": 1,\u000d\u000a      \"ColorNumber\": \"10\",\u000d\u000a      \"R\": 234,\u000d\u000a      \"G\": 240,\u000d\u000a      \"B\": 255,\u000d\u000a      \"ColorName\": \"Silky White\"\u000d\u000a    }\u000d\u000a  ]\u000d\u000a}",
  "ServerVersion": {
    "Major": 3,
    "Minor": 0
  },
  "Success": true,
  "Time": ""
}

RequestData after parsing:

{
  "Weight": 40,
  "Colors": [
    {
      "Index": 0,
      "ColorNumber": "3",
      "R": 235,
      "G": 236,
      "B": 238,
      "ColorName": "Ghost White"
    },
    {
      "Index": 1,
      "ColorNumber": "10",
      "R": 234,
      "G": 240,
      "B": 255,
      "ColorName": "Silky White"
    }
  ]
}

RequestData fields

• Weight (integer): thread weight of the series, for example 40. Read the weight from this field and don't parse it from the series id.
• Colors (array): every color of the series, in the order of the thread chart. Each entry has these fields:
  • Index (integer): position of the color in the thread chart, starting at 0. The numbering can have gaps, and some series store the value as a string, so accept both.
  • ColorNumber (string): the manufacturer's color number. It is always a string, even when it looks like a number (for example "20"), and it can contain letters (for example "10CG3"). Pass this value unchanged to GetThreadCone.
  • R, G, B (integer, 0-255): RGB value of the color.
  • ColorName (string, optional): name of the color. Most series have no color names, and some have names for only part of their colors. A color without a name either has no ColorName field, for example {"Index": 5, "ColorNumber": "21", "R": 40, "G": 41, "B": 44}, or has "ColorName": "".
  • ScanCode (integer, optional): scan code of the thread cone. It has up to 12 digits, so read it into a 64-bit integer. Only some series include it (for example A&E).

The response contains only Weight and Colors. It does not include the manufacturer; take that from GetThreadConeManufacturer.

Using the colors

To use a color in the Needle block of CreatePNG or CreateTC, map it like this:

• R, G, B go to Red, Green, Blue.
• ColorNumber and ColorName keep their names. Send "" when the color has no name.
• Weight goes to ThreadSize as a string, for example "40".

The same series id also works as ThreadTable in ACEParaOptimize.

Errors

• Unknown series, or ThreadCone.ConeSeries missing: Success is false and RequestData is Thread cone series not found: <ConeSeries>. The HTTP status is still 200, so always check Success.
• Server error while reading the thread chart: Success is false and RequestData is GetThreadConeList:<error message> (HTTP 200).
• Missing or misspelled RequestType: Success is false and RequestData is Error: unknown command! (HTTP 200).
• Missing or invalid license: HTTP 400, Success is false and RequestData is No licence token found. or Invalid licence token. See ZSK Web API License.
• "ThreadCone": null: the server can't read the request and answers with an error instead of a JobResponseType. Send the object with ConeSeries.

Notes

• This request is not billed and does not count against the license quota. You still need a valid WebApiLicense.
• This request only reads ThreadCone.ConeSeries. It ignores ThreadCone.Manufacturer and ThreadCone.ColorNumber.
• Put the lookup parameter inside the ThreadCone object, not at the top level. RequestType and all key names are case-sensitive, and the server silently ignores keys it doesn't recognize (a misspelled ThreadCone leads to "Thread cone series not found"). Matching of the series id itself is not case-sensitive.
• Leave out Client. With "Client": "ACE" the server handles the request as an ACE picture/vector job and answers with HTTP 400.
• Large series have several thousand colors (for example Candle Polyester Shade with about 4000). Thread charts rarely change, so cache the result on the client.