Wilcom Embroidery Web API Documentation

Welcome to the Wilcom Embroidery Web API documentation site.

Don’t have an account? Contact us here.

Home

There are a few documents for Wilcom API. They have been listed as below:

API Interface Specification

Introduction

Wilcom’s EWA Embroidery Web API is embroidery automation capabilities for web developers of embroidery and apparel companies who want to add embroidery capabilities to their websites, web applications, and internal business systems.

EWA API provides means to automatically visualize, create and manipulate embroidery designs and lettering. It provides selected capabilities of Wilcom’s embroidery lettering and digitizing software via Restful API and is fully compatible with Wilcom’s popular .EMB design format.

Purpose of this Document

This document describes the software interface details of the EWA Embroidery Web API software in technical terms for software developers.

References

Refer also to the separate Product Description document for an explanation of the API in non-technical end user terminology.

Definitions

Wilcom .EMB file. This is an embroidery design file created by a Wilcom embroidery design software. The EMB is a Wilcom propriety format, it includes stitches, objects with their properties, like shape, stitch type, underlay stitches, pull compensation, thread type and color sequence, multiple colorways, lettering objects, monogramming objects, optionally: artwork, fabric type and garment image. The EMB file can be exported to a so called “machine file” (for example a Tajima .DST file), a file that is readable by an embroidery machine and therefore the design can be stitched on the machine.  Most API calls provided by this service change the object properties of an EMB file (for example the text in a lettering object or the color sequence in an existing design) therefore achieving the required results that the user wants. We call these object properties “recipe” in this document. A recipe contains the instructions on what object properties need to be changed and to what value. Wilcom TrueView™ image. This is a transparent PNG file showing the embroidery design rendered in a 3-Dimensional simulation. It is used to show customers what the embroidery would look like if it was stitched on a garment.

Overview

Interface Overview

Developers access the functionality of the API by sending http request to the API URL with POST parameters and the API returns response with status ok (200) and result. The data is exchanged by using XML data packages.

All APIs return an XML string and take App Id and App Key as mandatory parameter and an XML string as an optional parameter. The content of the input XML and output XML strings is specific for each function. The root element of all input XML and output XML strings in the API is xml.

The set of parameters in an XML data package which specify how to construct an embroidery design is referred to as a design recipe, or simply recipe. Refer to details in the XML Data Packages section of this document.

All the files used by or produced by the API are also supplied as part of the input or output XML string in their own files element. The files are uniquely identified by a filename (much like on a file system) and can be referenced by that name in other parts of the input or output.

Functionality Overview

The Embroidery Web API provides functionality to:

  • Obtain design information existing embroidery Design files or from a recipe. For efficiency reasons this design information is always available upon return from any API method that creates a TrueView. 
  • Obtain all the EMB Colorway TrueView images from an existing EMB Design file or from a recipe.
  • Create a complete (lettering + decorations) design TrueView from a recipe.  This method is not recommended for near real time use cases.
  • Create Lettering with a simple preview view for one lettering decoration.
  • Create Lettering with TrueView from a given recipe.
  • Create Monogram with TrueView from a given recipe.
  • Create a ready for production embroidery data file in Wilcom .EMB file from a given recipe, and/or create a machine stitch file format to be used directly in production.
  • Edit lettering objects and monogram objects in an existing design with Trueview and product embroidery data file.
  • Obtain information about the Web API including version information and the Wilcom Alphabets that are supported.
  • Convert graphic files to include a transparent background.

Design Information and Images

The EWA provides information about existing designs including stitch count, height, width, number of colors and other embroidery metadata. This feature is implemented by the api/designInfo method. 

Clients can also obtain TrueView™ (realistic simulation of embroidery stitching) images of all design colorways from the EWA together with the metadata. This is implemented by the api/designTrueview method and is useful for batch upload use cases.

The api/designInfo method has better performance than the api/designTrueview method, since it does not generate the TrueViews™.

Create Embroidery Design Production Data

The EWA allow clients to produce an embroidery design (.EMB) and its TrueView™ using a simple set of components, such as other designs, lettering, team lettering and monogram. Certain properties of the components can be changed, and the components themselves can be positioned within a given location. This feature is implemented by api/newDesign method.

This API will be used to create the EMB file for a specific location. This EMB file is then used by the fulfilment centre for the sewing out of the embroidery into that specific location on the apparel.

The metadata for the generated design is also obtained by this API.

Create Embroidery Design TrueView™ Image

The EWA Services allow clients to produce a TrueView™ preview of the design that would be generated by the api/newDesign method. This feature is implemented by api/newDesignTrueview method.

The metadata for the generated design is also obtained by this method.

TrueView™ Images

Some of the APIs return TrueView™ images. Those images will be 1:1 scale at 96 dpi with a transparent background if the image file size is less than a threshold. They will be in the PNG format.

The TrueView image file size threshold is 4M by default. The dpi will reduce to half repeatedly until file size of TrueView image equal or less than threshold.

Create Fast Lettering Preview Image

The EWA allow clients to produce a fast preview of a single Lettering decoration, or a single Team Name Lettering decoration with a single team name. This feature is implemented by api/newLetteringPreview method.

Note that for performance reasons, the metadata for the lettering preview design obtained by this API is an estimate.

Edit design

The EWA allow clients to modify the lettering and monogram properties like text, font, colour etc. for an existing design. Client can choose to generate TrueView or embroidery design production data.  This feature is implemented by api/editDesign and api/editDesignTrueview. Also, the lettering properties like index, text and font are embedded in design info.  

Get API information

The EWA’s version information is returned by the api/info method. This method returns API information such as version and the available list of alphabets.

Bitmap Art Preview and Vector Art Preview

The EWA allows clients to preview a graphic file or PDF/EPS with a transparent background. This feature is implemented by api/bitmapArtPreview or api/vectorArtPreview method. Supported bitmap formats are listed in section 6 below.

Auto Digitize

The EWA allows clients to produce an embroidery design (.EMB) and its TrueView™ based on a provided graphic file or PDF/EPS. This feature is implemented by api/bitmapArtTrueview, api/bitmapArtDesign, api/vectorArtTrueview and api/vectorArtDesign method. Supported bitmap formats are listed in section Supported formats.

Error Handling

Error Handling

When the API detects an error with an API call, the EWA will return non-200 status code in response, e.g., 500(Internal Error), or 400(Bad Request), and others.  

Details of the error are defined in an XML data package, error_info which will return to client application. The error_info is described in Web API XML Data Package Definitions section in details. Error information: error_info XML Data.

EWA API Methods

Below are the links that can explain respective API calls in further details:

api/info

Action:

Obtain information about the API, such as the version and the available alphabets.

Post Parameters:

  • appId: Application id obtained from your Wilcom API Develop Portal account.
  • appKey: Application key obtained from your Wilcom API Develop Portal account.

Return Values:

On success, an XML string containing the API information:

<xml>
  <api_info ... /> 			// API information
</xml>

Remarks:

The method provides various information about the EWA.

See details in the XML Data Package Definitions section of this document.
API Information: api_info XML Data

api/designInfo

Action:

Obtain information about an existing design file, such as height, width, number of stitches, etc.

Post Parameters:

  • appId: Application id of Wilcom API Develop Portal account.
  • appKey: Application key of Wilcom API Develop Portal account.
  • requestXml: an XML string containing a list of a single design file, whose metadata you want to obtain:
<xml> 
  <files> 
    <file ... />          // design file 
  </files> 
</xml>

Return Values:

On success, an XML string containing the design information:

<xml> 
  <design_info ... />         // design information 
</xml>

Remarks:

The method allows the client to obtain various information about the design.

See details in the XML Data Package Definitions section of this document.
Design Information: design_info XML Data

api/designTrueview

Action:

Obtain a 1:1 TrueView™ realistic embroidery simulation image for each of the colorways of an existing design that you provide.  The TrueView™ image will have a transparent background (i.e. PNG file with transparency).

Also obtain metadata information about the design, such as height, width, number of stitches, etc.

Post Parameters:

  • appId: Application id of Wilcom API Develop Portal account.
  • appKey: Application key of Wilcom API Develop Portal account.
  • requestXml: an XML string containing a list of a single design file, whose metadata and TrueView™ files to obtain:
<xml>
   <design … />
   <trueview_options … />
   <recolor … />
  <files>
    <file ... />				// design file
  </files>
</xml>

Return Values:

On success, an XML string containing the design information, and TrueView™ files:

<xml>
  <design_info ... /> 				// design information
  <files>					// trueviews
    <file ... />
    <file ... />
  </files>
</xml>

Remarks:

The API allows the client to obtain various information about the design and the TrueViews™ of current, all or specified colorways in design.

design is optional parameter. The default behaviour is equal colorwaytype is current.

The filename of file in response will be colorway name plus extension except when a design contains more than one colorway and the colorwaytype is current. In this scenario, the filename will be Default.png. This tiny problem will be fixed soon.

trueview_options is optional parameter, specified the options like dpi for resulting trueview.

trueview_options is optional parameter, specified the colors to replace the colorway of design.

See details in the XML Data Package Definitions section of this document.

api/newDesignTrueview

Action:

Obtain a transparent TrueView™ image of a new set of decorations in a combined design which is created based on the design recipe provided. The TrueView™ image is 1:1 size will have a transparent background (i.e. PNG file with transparency).

Also obtain information about the produced design, such as height, width, number of stitches, etc, as the api/designInfo function.

Post Parameters:

  • appId: Application id of Wilcom API Develop Portal account.
  • appKey: Application key of Wilcom API Develop Portal account.
  • requestXml: an XML string containing the full specification of the components of design:
<xml>
  <recipe ... /> 			// recipe
  <files ... />				// files used by the recipe
</xml>

Return Values:

On success, an XML string containing the generated TrueView and the design information:

<xml>
  <files>
    <file ... />			// resulting trueview file
  </files>
  <design_info ... /> 			// design information
</xml>

Remarks:

The method will create a new design by combining the multiple decorations supplied and position them according to the transforms specified by recipe.

It will then create a transparent bitmap of the produced design that will be returned in files part of the return value, named according to the trueview_file parameter of the output component of the recipe.

It will then create the design information about the produced design that will be returned in design_info part of the return value. This method does not return the actual embroidery design data – only an image of what the design would look like. Use api/newDesign to get the actual embroidery data.

api/newDesign

Action:

Obtain a single design file of a new set of decorations in a combined design which is created based on the design recipe provided. Returns the actual design data in .EMB format, and/or other supported formats.

Also, optionally generate a transparent TrueView™ image of the decorations as api/newDesignTrueview function. Also, obtain information about the produced design, such as height, width, number of stitches, etc, as the api/designInfo function.

Post Parameters:

  • appId: Application id of Wilcom API Develop Portal account.
  • appKey: Application key of Wilcom API Develop Portal account.
  • requestXml: an XML string containing the full specification of the components of design:
<xml>
  <recipe ... /> 			// recipe
  <files ... />				// files used by the recipe
</xml>

Return Values:

On success, an XML string containing the generated design, and optionally its TrueView™ and the design information:

<xml>
  <files>
    <file ... />			// resulting design file
    <file ... />			// optional trueview file
  </files>
  <design_info ... /> 			// design information
</xml>

Remarks:

The method will create a new composite design combining all the decorations supplied and position them according to the transforms specified by recipe.

It will then produce an embroidery design data file that will be returned in files part of the return value, named according to the design_file parameter of the output component of the recipe.

It will then optionally create a transparent bitmap of the produced design that will be returned in files part of the return value, named according to the trueview_file parameter of the output component of the recipe. It will then create the design information about the produced design that will be returned in design_info part of the return value.

api/editDesignTrueview

Action:

Obtain a transparent TrueView™ image by modifying the properties of lettering objects and monogram lettering objects inside an existing design. The TrueView™ image is 1:1 size will have a transparent background (i.e. PNG file with transparency).

Also obtain information about the produced design, such as height, width, number of stitches, etc, as the api/designInfo function.

Post Parameters:

  • appId: Application id of Wilcom API Develop Portal account.
  • appKey: Application key of Wilcom API Develop Portal account.
  • requestXml: an XML string containing the full specification of the components of design:
<xml>
  <recipe>
<design   ... />		//design
<output … />			//output
  </recipe>
  <files   … />			//files
</xml>

Return Values:

On success, an XML string containing the generated Trueview:

<xml>
  <files>
    <file ... />			// resulting trueview file
  </files>
  <design_info ... /> 			// estimated design information
</xml>

Remarks:

The method will create a design based on an existing design with modified properties of lettering object inside. The existing design is appointed by design component and the design file content is in files part.

The properties of lettering object are in lettering_objects component inside design.

The properties of monogram object are in monogram_objects component inside design.

It will then create a transparent bitmap of the produced design that will be returned in files part of the return value, named according to the trueview_file parameter of the output component of the recipe.

It will then create the design information about the produced design that will be returned in design_info part of the return value. This method does not return the actual embroidery design data – only an image of what the design would look like. Use api/editDesign to get the actual embroidery data.

api/editDesign

Action:

Obtain a single design file by modifying the properties of lettering objects and monogram objects inside an existing design. Returns the actual design data in .EMB format, and/or other supported formats.

Also, optionally generate a transparent TrueView™ image as api/editDesignTrueview function. Also, obtain information about the produced design, such as height, width, number of stitches, etc, as the api/designInfo function.

Post Parameters:

  • appId: Application id of Wilcom API Develop Portal account.
  • appKey: Application key of Wilcom API Develop Portal account.
  • requestXml: an XML string containing the full specification of the components of design:
<xml>
  <recipe>
    <design   ... />			//design
    <output … />			//ouput
  </recipe>
  <files   … />				//files
</xml>

Return Values:

On success, an XML string containing the generated Trueview:

<xml>
  <files>
    <file ... />			// resulting trueview file
  </files>
  <design_info ... /> 			// estimated design information
</xml>

Remarks:

The method will create a design based on an existing design with modified properties of lettering object inside. The existing design is appointed by design component and the design file content is in files part.

The properties of lettering object are in lettering_objects component inside design.

The properties of monogram object are in monogram_objects component inside design.

It will then produce an embroidery design data file that will be returned in files part of the return value, named according to the design_file parameter of the output component of the recipe.

It will then optionally create a transparent bitmap of the produced design that will be returned in files part of the return value, named according to the trueview_file parameter of the output component of the recipe. It will then create the design information about the produced design that will be returned in design_info part of the return value.

api/newLetteringPreview

Action:

Generate a fast, small transparent image file (non-Trueview) of a single new Lettering decoration or a single new Team Name Lettering decoration with a single name for a single location.

Also obtain estimated information about the produced design, such as height, width, number of stitches, etc, as the api/designInfo function.

Post Parameters:

  • appId: Application id of Wilcom API Develop Portal account.
  • appKey: Application key of Wilcom API Develop Portal account.
  • requestXml: an XML string containing the full specification of the components of design:
<xml>
  <recipe ... /> 			// recipe
</xml>

Return Values:

On success, an XML string containing the generated preview:

<xml>
  <files>
    <file ... />			// resulting trueview file
  </files>
  <design_info ... /> 			// estimated design information
</xml>

Remarks:

The method will position a single Lettering or Team Name Lettering decoration according to the transform specified by recipe.

It will then create a fast, small non-trueview transparent bitmap of the produced design that will be returned in files part of the return value, named according to the trueview_file parameter of the output component of the recipe.

The bitmap produced by this function is of lower visual quality than the TrueView ™ bitmap produced by api/newDesignTrueview function. It contains a much simpler visual representation of the stitched area.

It will then create the estimated design information about the produced design that will be returned in design_info part of the return value.

For performance reasons, the design information produced by this function is an estimate. It can differ slightly if compared to actual design info produced by api/designInfo or api/newDesign with the same input.

This function is much faster than api/newDesignTrueview, and should be used where speed is more important than image quality.

api/bitmapArtPreview

Action:

The API accepts a bitmap image, makes the background as transparent and converts the image to PNG format.

The supported bitmap image formats are listed here:  Bitmap formats

The original PNG file will be returned if the input PNG already has transparent pixels.

If the input GIF already has transparent pixels, only converts it to PNG.

Post Parameters:

  • appId: Application id of Wilcom API Develop Portal account.
  • appKey: Application key of Wilcom API Develop Portal account.
  • requestXml: an XML string containing a single bitmap file:
<xml>
  <bitmap … />
  <files>
    <file ... />				// bitmap  file.
  </files>
</xml>

Return Values:

On success, an XML string containing the design information:

<xml>
  <source_bitmap_info  .. /> 			// source bitmap  information
  <files>
    <file ... />				// result PNG file.
  </files>
</xml>

Remarks:

The bitmap appoints which file will be processed in files . Please read Bitmap Recipe: bitmap XML Data for more information.

The source_bitmap_info returns some properties of the input bitmap. Please read Source Bitmap Recipe: source_bitmap_info XML Data for more information.

The files contains the file name and file content of bitmap files in request which will be processed and processed image in the return. Please read Files: files XML Data for more information.

api/vectorArtPreview

Action:

The API accepts a vector file, converts it to PNG image with transparent background.

The supported vector formats are listed here: Vector formats.  

The default DPI is 96 when generating image. The transparent edge of result image will be removed.

Post Parameters:

  • appId: Application id of Wilcom API Develop Portal account.
  • appKey: Application key of Wilcom API Develop Portal account.
  • requestXml: an XML string containing a single vector file:
<xml>
  <vector … />
  <files>
    <file ... />				// vector file.
  </files>
</xml>

Return Values:

On success, an XML string containing the design information:

<xml>
  <files>
    <file ... />				// result PNG file.
  </files>
</xml>

Remarks:

The vector appoints which file will be processed in files .

Please read Vector Recipe: vector XML Data for more information.

The files contains the file name and file content of bitmap files which will be processed and processed image in the return. Please read Files: files XML Data for more information.

api/bitmapArtDesign

Action:

Obtain a single design file by auto digitizing the bitmap image. Actual design data in .EMB format, and/or other supported formats is returned.

The supported bitmap image formats are listed here:  Bitmap formats

The API removes the background as api/bitmapArtPreview did. And then execute auto digitize task.

Also, optionally generate a transparent TrueView™ image of the design as api/newDesignTrueview function. Obtain information about the produced design, such as height, width, number of stitches, etc, as the api/designInfo function.

Post Parameters:

  • appId: Application id of Wilcom API Develop Portal account.
  • appKey: Application key of Wilcom API Develop Portal account.
  • requestXml: an XML string containing a single bitmap file:
<xml>
  <bitmap … />
  <autodigitize_options … />
  <output … />
  <files>
    <file ... />			// bitmap  file.
  </files>
</xml>

Return Values:

On success, an XML string containing the design information:

<xml>
  <files>
    <file ... />		// resulting design and trueview file
  </files>
  <design_info ... /> 		// estimated design information
</xml>

Remarks:

The bitmap appoints which file will be processed in files . Please read Bitmap Recipe: bitmap XML Data for more information.

The autodigitize_options appoints some options which will be used when auto digitizing Please read Auto Digitize Options Recipe: autodigitize_options XML Data for more information.

The output specifies the output format and version of the function. Please read Output for more information.

The files contains the file name and file content of bitmap files in request which will be processed and created embroidery design and TrueView in the return.  Please read Files: files XML Data for more information.

It will then create the design information about the produced design that will be returned in design_info part of the return value. Please read Design Information: design_info XML Data for more information.

There are some limitations for input bitmap file. Please read Auto digitize limitations.

api/vectorArtDesign

Action:

Obtain a single design file by auto digitizing the vector artwork. Actual design data in .EMB format, and/or other supported formats is returned.

The supported vector formats are listed here: Vector formats. 

Also, optionally generate a transparent TrueView™ image of the design as api/newDesignTrueview function. Obtain information about the produced design, such as height, width, number of stitches, etc, as the api/designInfo function.

Post Parameters:

  • appId: Application id of Wilcom API Develop Portal account.
  • appKey: Application key of Wilcom API Develop Portal account.
  • requestXml: an XML string containing a single bitmap file:
<xml>
  <vector … />
  <autodigitize_options … />
  <output … />
  <files>
    <file ... />			// vector  file.
  </files>
</xml>

Return Values:

On success, an XML string containing the design information:

<xml>
  <files>
    <file ... />		// resulting design and trueview file
  </files>
  <design_info ... /> 		// estimated design information
</xml>

Remarks:

The vector appoints which file will be processed in files . Please read Vector Recipe: vector XML Data for more information.

The autodigitize_options appoints some options which will be used when auto digitizing Please read Auto Digitize Options Recipe: autodigitize_options XML Data for more information.

The output specifies the output format and version of the function. Please read Output for more information.

The files contains the file name and file content of bitmap files in request which will be processed and created embroidery design and trueview in the return.  Please read Files: files XML Data for more information.

It will then create the design information about the produced design that will be returned in design_info part of the return value. Please read Design Information: design_info XML Data for more information.

There are some limitations for input vector file. Please read Auto digitize limitations.

api/bitmapArtTrueview

Action:

Obtain a transparent TrueView™ image by auto digitizing the bitmap image.

The supported bitmap image formats are listed here:  Bitmap formats

The API removes the background as api/bitmapArtPreview did. And then execute auto digitize task.

Also obtain information about the produced design, such as height, width, number of stitches, etc, as the api/designInfo function.

Post Parameters:

  • appId: Application id of Wilcom API Develop Portal account.
  • appKey: Application key of Wilcom API Develop Portal account.
  • requestXml: an XML string containing a single bitmap file:
<xml>
  <bitmap … />
  <autodigitize_options … />
  <output … />
  <files>
    <file ... />			// bitmap  file.
  </files>
</xml>

Return Values:

On success, an XML string containing the design information:

<xml>
  <files>
    <file ... />			// resulting trueview file
  </files>
  <design_info ... /> 			// estimated design information
</xml>

Remarks:

The bitmap appoints which file will be processed in files . Please read Bitmap Recipe: bitmap XML Data for more information.

The autodigitize_options appoints some options which will be used when auto digitizing Please read Auto Digitize Options Recipe: autodigitize_options XML Data for more information.

The output specifies the output format and version of the function. Please read Output for more information.

The files contains the file name and file content of bitmap files in request which will be processed and created embroidery trueview in the return.   Please read Files: files XML Data for more information.

It will then create the design information about the produced design that will be returned in design_info part of the return value. Please read Design Information: design_info XML Data for more information.

There are some limitations for input bitmap file. Please read Auto digitize limitations.

api/vectorArtTrueview

Action:

Obtain a transparent TrueView™ image by auto digitizing the vector artwork.

The supported vector formats are listed here: Vector formats. 

Also obtain information about the produced design, such as height, width, number of stitches, etc, as the api/designInfo function.

Post Parameters:

  • appId: Application id of Wilcom API Develop Portal account.
  • appKey: Application key of Wilcom API Develop Portal account.
  • requestXml: an XML string containing a single bitmap file:
<xml>
  <vector … />
  <autodigitize_options … />
  <output … />
  <files>
    <file ... />			// vector file.
  </files>
</xml>

Return Values:

On success, an XML string containing the design information:

<xml>
  <files>
    <file ... />			// resulting trueview file
  </files>
  <design_info ... /> 			// estimated design information
</xml>

Remarks:

The vector appoints which file will be processed in files . Please read Vector Recipe: vector XML Data for more information.

The autodigitize_options appoints some options which will be used when auto digitizing Please read Auto Digitize Options Recipe: autodigitize_options XML Data for more information.

The output specifies the output format and version of the function. Please read Output for more information.

The files contains the file name and file content of bitmap files in request which will be processed and created embroidery TrueView in the return.   Please read Files: files XML Data for more information.

It will then create the design information about the produced design that will be returned in design_info part of the return value. Please read Design Information: design_info XML Data for more information.

There are some limitations for input vector file. Please read Auto digitize limitations.

API XML Data Package Definitions

XML data packages are comprised of named elements which contain attributes.

Below links explains API XML Data Package in further details.

Error information: error_info XML Data

When the API detects an error with an API call, the EWA will return non-200 status code in response, e.g., 500(Internal Error), or 400(Bad Request), and others. 

Details of the error are defined in an XML data package, error_info which will return to client application. The error_info is described below.

API error condition at Web API Level



<error_info
errorcode = “111” 					// API error code
message = “Exception occurs when logging in 3scale.”	// short error message
> 				
  <details>
      CS_threescale.ApiException: application_not_found : application with id="46329c141" was not found
      at CS_threescale.Api.aux_authorize(Int32 key_type, String id, String key)
      at Wilcom.EWA.ThreeScale.Login(String appId, String appKey, String[] metricNames)
      at Wilcom.EWA.Controllers.BaseController.Authenticate3Scale(String appId, String appKey, AuthorizeResponse&amp; threeScaleReponse)
  </details>
</error_info>

Usage:

The error_info xml string is used in:

  • All methods.

Remarks:

The error_info will be returned if something wrong when processing request. The response’s status code is not ok (200).

errorcode is an integer. Each code represents a kind of errors. Here is the list:

  • 100: internal Error, Unknown exception occurs in API. The details element will carry more information. Http status code is InternalServerError(500).
  • 101: Input Error, one or some post parameters are missing or wrong. message describes the reason. Http status code is BadRequest(400).
  • 102: Recipe Error, exception occurs when serializing or deserializing XML data packages.  The details element will carry more information. Http status code is InternalServerError(500).
  • 103: Design Format Error, the input or output design file format is not supported by API. message describes the reason. Http status code is BadRequest(400).
  • 110: Authentication Fail, fail to authenticate App Id and App Key. The details element will carry more information. Http status code is Unauthorized (401).
  • 111: Authentication Error, exception occurs when authenticating App Id and App Key. The details element will carry more information. Http status code is Unauthorized (401).
  • 120: CAD Server Error, exception occurs inside CAD Server. cadcode has error code returned by CAD Server. The details element will carry more information. Http status code is InternalServerError(500).
  • 121: CAD Interoperation Error, exception occurs when calling CAD Server. The details element will carry more information. Http status code is InternalServerError(500).

message is a short message to describe the error.

details are detailed error information. It will help programmer to develop client side or API developer to analysis the error.

Details Return Code: ERROR_FILE_SECURITY_INVALID – this specific return code is received when the API call uploads an EMB file that was created by an unlicensed Wicom EmbroideryStudio software.

API error condition related to the underlying CAD Server

Cad server has its own error code to represent different errors. A dedicated attribute cadcode is for it. For example:

<error_info
errorcode = “120” 					// API error code
message = “Exception occurs inside CAD Server.”		// short error message
cadcode=”0x1E”					// cad error code
> 				
  <details>						// detailed error information
       	Wilcom.Servers.CADEmbServer.CADException: Call to EmbServer_GetDesignInfo failed.
Return code: ERROR_READ_FAULT
   at Wilcom.Servers.CADEmbServer.CADEmbServer.CallCadServerAPI(String methodName, Object[] methodParams)
   at Wilcom.Servers.CADEmbServer.CADEmbServer.GetDesignInfo(String designFilename)
   ……					
  </details>
</error_info>

Usage:

The error_info xml string is used in:

  • All methods.

Remarks:

cadcode is only available when errorcode is 120. It is hex string returned from CAD Server. The known cad codes are:

0x22100011: ERROR_INCORRECT_XML_DATA_STRUCTURE, the xml structure is incorrect.

0x20000100: ERROR_INVALID_VERSION, the design_version specified in recipe is invalid.

0x20000104: ERROR_FILEVERSION_TO_GREAT, a design file specified in recipe could not be opened because it was created with newer version of software.

0x20000106: ERROR_FILE_VERSION_OBSOLETE, a design file specified in recipe could not be opened because it was created with old version of software which isn’t supported anymore.

0x22100010: ERROR_NOT_A_SINGLE_LETTERING_DESIGN: the recipe does not contain a single Lettering decoration specification or a single Team Name Lettering with a single name decoration specification.

0x54F:  ERROR_INTERNAL_ERROR, an internal error has occurred.

0x22100001: ERROR_BAD_PTR, an internal error has occurred.

0x1E: ERROR_READ_FAULT, this file’s format does not match the expected format for this extension.  For stitch design files, the source software may be creating non-standard formats.  Check with the source of the file.

0x21000014: ERROR_INVALID_DESIGN_EXTENTS_STITCH, the design cannot be output because part of the design lies outside the stitching area.

0x21000018: ERROR_INVALID_HOOP_FOR_MACHINE_MODEL, the opened design contains a Hoop which is not supported on the target machine.

0x21000032: ERROR_COLOR_SECTION_TOO_BIG, the design cannot be split as it contains a color part (layer) for which the stitch count exceeds the limit. 0x21000033: ERROR_DESIGN_EXCEEDS_MACHINE_STITCH_AREA, the design cannot be output because part of the design lies outside the maximum stitching area of the target machine.

API Information: api_info XML Data

<api_info> 				// api information
  <api_version				// api version
     major="4" 				// version major
     minor="5" 				// version minor
     build="9"				// build number
     private="0"			// private number
  />
  <alphabets>				// list of alphabets 
    <alphabet 
       name="Block1"			// name of alphabet
    />
    <alphabet 
       name="Block2"
    />
    <alphabet 
       name="London"
    />
    <alphabet 
       name="Alice"
    />
  </alphabets>
  <full_version>			// full version information
    <api_version 			// api version as above
       major="4" minor="5" build="9" private="0" />
    <internal_api_version 		// internal api version
       major="28" minor="1" build="2" private="0" />
  </full_version>
</API_info>

Usage:

The api_info xml string is used in:

Remarks:

The api_info consists of an api_version and a list of supported alphabets on the system.

The api_version specifies the major, minor, build and the private number of the API version.

The information for each alphabet contains the alphabet name which should be supplied in the lettering decorations. The API can only create lettering decorations from alphabets that are returned by this function. The alphabet name may have spaces in it.

The full_version contains more detailed version information. It contains an internal_api_version for support. In the future, the API information may be extended with other data.

Files: files XML Data

<files>					// list of files
  <file					// file
     filename="design1.emb"		// filename including the type
     filecontents="..."			// contents of the file
  />
  <file					// file
     filename="design2.emb"		// filename including the type
     filecontents="..."			// contents of the file
  />
  <file					// file
     filename="trueview.png"		// filename including the type
     filecontents="..."			// contents of the file
  />
</files>

Usage:

The files xml string is used in:

Remarks:

The files xml string specifies the list of files used or produced by a given function. It can contain one or more files.

The file specifies a single file that can be used or produced by the API.

The filename specifies the name of the file, including the type. The name is a unique identifier of the file that could be referenced in other parts of the input or output.

The filecontents encodes the contents of the file as a base64 string.

Note that some characters are valid in filename of filesystem but are invalid in xml.

For any attribute value:

  • “<”  becomes  “&lt;”
  • “&”  becomes  “&amp;”
  • ‘”‘  becomes  ‘&quot;’ (if you are using quote(“) to  delimit the attribute value)
  • “‘”  becomes  “&apos;” (if you are using apostrophe(‘)  to delimit the attribute value)

Design Information: design_info XML Data

<design_info					// design information
    machine_name="Melco"         		// embroidery machine name
    num_stitches="49569"         		// number of stitches
    num_colours="7"              		// number of colors
    num_trims="21"               		// number of trims
    num_objects="100"            		// number of embroidery objects
    num_colour_changes="13"      		// number of color changes
    height="215.572222"          		// double, in mm
    width="138.633333"           		// double, in mm
  />
  <colorways>                      		// list of colorways
    <colorway 					// colorway information
      name="Colorway 1"				// colorway name
      file="Colorway 1.png"			// optional colorway trueview file
      bkg_colr=”12632256”			//colorway background color
      current=”true” >				//if this colorway is current 
        <threads>				// list of colorway threads
          <thread . . . />
          <thread . . . />
          <thread . . . />
        </threads>
      </colorway>
    <colorway .../>				// optionally more colorways
  </colorways>	
    <stop_sequence>				// stop sequence
      <stop_record 				// individual stop record
        color_idx="0" 				// index into colorway threads
        num_stitches="73" 			// number of stitches
        element="" />				// free text element string
      <stop_record . . . />
      <stop_record . . . />
      <stop_record . . ./>
    </stop_sequence>
<lettering_objects>				//lettering objects info
    <lettering_object index="0">		//lettering object info if design has one or more
        <simple_lettering  . . .   />
        <thread … />
    </lettering_object>
</lettering_objects>
<monogram_objects>			// monogram objects info
   <monogram_object index="0">		// monogram object info if design has one or more
       <monogram_lettering … />
       <monogram_ornament … />
   </monogram_object>
</monogram_objects>
</design_info>

Usage:

The design_info xml string is used in:

Remarks:

Design information estimation

For performance reasons, the design information produced by the api/newLetteringPreview function is an estimate. It can differ slightly if compared to actual design info produced by api/designInfo or api/newDesign with the same input.

Most of the fields are estimated exactly. However, some fields are estimated with less than 100% accuracy. The list below contains the accuracy for estimated fields. For the fields where the estimation accuracy is not specified, the field value is estimated exactly, and is identical to the actual design information field value.

Design information

The design_info provides the following information about the design:

The machine_name specifies the embroidery machine format of the design.

The num_stitches specifies the number of stitches in the design. When estimated, the accuracy is +/- 10%.

The num_colours specifies the number of colours in the design. When estimated, the value is always 1.

The num_trims specifies the number of trims in the design. When estimated, the value is always 0.

The num_objects specifies the number of embroidery objects in the design.

The num_colour_changes specifies the number of color changes in the design. When estimated, the value is always 0.

The height specifies the height of the design in mm.

The width specifies the width of the design in mm.

The colorways contains the list of all colorways in the design.

In the future, the design information may be extended with other data.

Colorway information

The information for each colorway contains the colorway name which should be supplied in the design decorations.

The file specifies the colorway’s TrueView™ bitmap filename, and is returned only by the api/designTrueview function.

bkg_color is the background color of the colorway. This attribute always has value. The background color saved in template is returned for stitch designs (DST, PES, etc.). The background color saved in design is returned for native designs (EMB, ART, etc.).

The colorway also contains an ordered list of threads that comprise the colorway.

Stop Sequence information

The stop_sequence information describes the stops in the design, by means of an ordered list of stop_records.

Each stop record contains a color_idx, which specifies the zero-based index of the thread in any colorway’s threads list. Note that in certain rare cases (e.g., designs with borers), there is no color applicable to a particular stop record, in which case the color_idx for that stop record would contain -1.

The num_stitches specifies the number of stitches in the stop record.

The element string can contain free text describing the stop record.

Lettering Objects information

The lettering_objects information describes the lettering objects in a design. It contains an ordered list of lettering_object records. Note that the lettering objects that are part of a Team Name Lettering or Monogram cannot be changed using these means and are therefore not included in the list.

Each lettering_object contains an index, which specifies the zero-based index of the lettering object in the list of all lettering objects in design.  The simple_lettering and thread specify lettering settings and thread for the lettering object.

Monogram Objects information

The monogram_objects information describes the monogram objects in a design. It contains an ordered list of monogram_object records. Each monogram_object contains an index, which specifies the zero-based index of the monogram object in the list of all monogram objects in design.  The monogram_lettering and monogram_ornament specify lettering settings and ornament settings.

Design Recipe: recipe XML Data

<recipe>				// recipe
  <location . . .  />	
  <decorations . . . />
  <output . . . />
</recipe>

Usage:

The recipe xml string is used in:

Below links explains XML tags in further details.

Location

<location 
      width="100.0" 			// double, in mm
      height="100.0" 			// double, in mm
  />

The location xml specifies the size of the location in mm to be used as a reference by the API.

Decorations

<decorations>
    <design  . . .  />			//Design component
    <lettering  . . .  />		//Lettering component
    <team_name_lettering  . . .  /> 	//Team Lettering component
</decorations>

There can be one or more decorations components.

The decorations components are design, lettering, team_lettering. At least one decoration is required. The order of decorations in the xml string specifies the order of stitching in the final design.

api/newLetteringPreview function expects a single lettering decoration only.

Transform

<transform 
    scale="1.0" 			// double, min 0.8, max 1.2
    mirror="none" 			// none, horizontal, vertical, both
    rotation="0" 			// +/-, rotation angle in degrees 
    dx="0.0" 			        // double, in mm from location top-left
    dy="0.0" 			        // double, in mm from location top-left
/>

Each decoration is accompanied by the specification of a transform. Using this transform, the API will transform the original decoration according to the following order:

  • Scale around decoration centre.
  • Mirror horizontally, vertically or both
  • Rotate around decoration centre
  • Translate right/down from the top-left corner of the decoration.

The scale parameter can range from 0.8 to 1.2. This enforces the rule that scaling of embroidery should be restricted to 20% up or down.

The mirror parameter string can be one of “none”, “horizontal”, “vertical”, “both”

The rotate parameter is an angle in degrees. Positive angle is clockwise rotation, negative angle is counterclockwise rotation.

The translation parameter is in mm. The origin of translation is the top-left corner of the location. The positive x-direction is to the right. The positive y-direction is down. Note that it is the responsibility of the client to make sure that after the decoration is transformed, its bounds are still inside the location rectangle.

Thread

<thread 
   color="32768" 		// RGB as int
   code="1001" 			// free text string
   brand="Madeira" 		// free text string
   description="Green" 		// free text string
/>

The colour of the embroidery thread is specified by the thread component.

The color parameter is an integer containing the RGB values of the colour. It is obtained by the following code:

int colorRGB = color.Red + (color.Green << 8) + (color.Blue << 16);

The code, brand and description strings are free-text strings for the purposes of production. They are typically obtained from an embroidery thread chart.

Design

<design 
   file="logo1.emb"		// name of the emb file
   colorwaytype="specified"	// colorway type:current, all or specified
   colorway="White">		// name of the colorway

   <transform... />
   <lettering_objects... />	// opt change lettering objects in a design
   <monogram_objects... />	// opt change monogram objects in a design
</design>

The design decoration is specified by a named design file, an optional design colorwaytype, colorway, and a transform.

Additionally, if the design contains existing lettering objects and monogram objects, they can be modified using lettering_objects and monogram_objects by calling editDesign/editDesignTrueview. The newDesign/newDesignTrueview will ignore lettering_objects and monogram_objects element.

The file itself must be supplied in the list of files.

The colorwaytype parameter specifies what kind of colorway image will be returned. It can be one of the following 3 values:

  • “current”: Default value. Returns the TrueView of the current colorway.
  • “all”: Returns TrueViews for all colorways. Ignored in newDesignTrueview for now.
  • “specified”: The colorway parameter only works with this option. Only the TrueView of the colorway named by colorway is returned. If the colorway is not specified, newDesignTrueview will use the current colorway. designTrueview will return an error.

The transform element will be ignored in designTrueview.

Trueview Options

<trueview_options 
   dpi="120"			// The dpi of trueview
/>

The options for output TrueView when calling designTrueview API. Whole trueview_options is optional. The dpi parameter is an integer, specified the dpi of output TrueView. Default value is 96. Default value will be use if it is missing or equal or less than 0. The Max value is 300.

Lettering Objects

<lettering_objects>				
   <lettering_object index="0">		
      <simple_lettering... />		//optional change lettering parameters
      <thread... />			//optional change lettering color
   </lettering_object>
   <lettering_object index="n">		
      <simple_lettering... />			
      <thread … />				
   </lettering_object>
</lettering_objects>

If a design contains lettering objects, they can be modified by using lettering_objects parameter by calling editDesign or editDesignTrueview.  Whether a design contains lettering objects can be determined in design_info which is returned by several API methods like designInfo or designTrueview.

Multiple lettering objects can be modified in one call. Each lettering_object specifies a modification for a single lettering object. The index specifies the ordinal zero-based index of the lettering object in the design that should be modified.

The system supports modification of most lettering parameters (using simple_lettering) as well as modification of lettering color (using thread).

The subset of simple_lettering parameters supported for modification is text, alphabet_name, height, bold and italic.

All parameters inside lettering_object are optional and the system will modify only the ones which are supplied. Thus, it is possible to say only change the text, or only the color, or only the text and the alphabet.

For example:

  1. Modify the color of the first lettering object in a design:
<lettering_objects>
    <lettering_object index = "0">
        <thread color="32768" code="xx" brand="xx" description="xx" />
    </lettering_object> 
</lettering_objects>
  1. Modify the text of the first lettering object in a design
<lettering_objects>
    <lettering_object index = "0">
        <simple_lettering text="New Name"/>
    </lettering_object> 
</lettering_objects>
  1. Modify the text and alphabet of the first object; and the text and color of the second lettering object in a design
<lettering_objects>
    <lettering_object index = "0">
        <simple_lettering text="John" alphabet_name="Agatha"/>
    </lettering_object> 
    <lettering_object index = "1">
        <simple_lettering text="Smith"/>
        <thread color="32768" code="xx" brand="xx" description="xx" />
    </lettering_object> 
</lettering_objects>

Client side must guarantee the alphabet used by editDesign/editDesignTrueview is supported by EWA in both of following scenarios:

  • Modified alphabet_name of lettering_object must be supported by EWA.
  • When modify other attributes than alphabet_name for a lettering_object, the original alphabet of the lettering_object must be supported by EWA.

API searches the color in palette of the design if a thread color is appointed when calling editDesign/editDesignTrueview . If the color is found, the corresponding stop of the lettering object will use the index of the found color. Otherwise, API will create new thread color with supplied color, value, code, brand and description in the palette of the design, and the corresponding stop of the lettering object will use the index of the new thread color.

For the design has more than 1 colorways, the editDesign/editDesignTrueview only works on one colorway: appointed colorway (by colorway of design) or current colorway (no colorway appointed).

Monogram Objects

<monogram_objects>				
   <monogram_object index="0">		
      <monogram_lettering... >		//optional change lettering parameters
         <thread... />			//optional change lettering color
      </monogram_lettering>
      <monogram_ornament ... />		//change ornament is not supported yet
   </monogram_object>
   <monogram_object index="n">		
      <monogram_lettering... >			
            <thread... />		
      </monogram_lettering>
      <monogram_ornament … />		
   </monogram_object>
</monogram_objects >

If a design contains monogram objects, they can be modified by using monogram_objects parameter by calling editDesign or editDesignTrueview.  Whether a design contains monogram objects can be determined in design_info which is returned by several API methods like designInfo or designTrueview.

Multiple monogram objects can be modified in one call. Each monogram_object specifies a modification for a single monogram object. The index specifies the ordinal zero-based index of the monogram object in the design that should be modified.

The system supports modification of monogram lettering parameters (using monogram_lettering) as well as modification of lettering color (using thread). Modify ornament properties is not supported yet. There is a limitation to change color for some special alphabets that have letters with saved colors/functions, see Letters created with unchecked remove functions.

The subset of monogram_lettering parameters supported for modification is text, alphabet_name, and height.

All parameters inside monogram_object are optional and the system will modify only the ones which are supplied. Thus, it is possible to say only change the text, or only the color, or only the text and the alphabet.

For example:

  1. Modify the color of the first monogram lettering object in a design:
<monogram_objects>
   <monogram_object index="0">
      <monogram_lettering>
         <thread color="65535" code="xx" brand="xx" description="xx"  />
      </monogram_lettering>
   </monogram_object>
</monogram_objects>
  1. Modify the text of the first monogram lettering object in a design
<monogram_objects>
   <monogram_object index="0">
      <monogram_lettering text="XYZ"/>          
   </monogram_object>
</monogram_objects>
  1. Modify the text, alphabet, and style of the first object; and the text and color of the second monogram object in a design
<monogram_objects>
   <monogram_object index="0">
      <monogram_lettering text="XYZ" style="style_17" alphabet_name="AGATHA" >            
      </monogram_lettering>
   </monogram_object>
   <monogram_object index="1">
      <monogram_lettering text="789">
         <thread color="65535" code="xx" brand="xx" description="xx" />
      </monogram_lettering>
   </monogram_object>
</monogram_objects>

Client side must guarantee the alphabet used by editDesign/editDesignTrueview is supported by EWA in both of following scenarios:

  • Modified alphabet_name of monogram_object must be supported by EWA.
  • When modify other attributes than alphabet_name for a monogram_object, the original alphabet of the monogram_object must be supported by EWA.

API searches the color in palette of the design if a thread color is appointed when calling editDesign/editDesignTrueview. If the color is found, the corresponding stop of the lettering object will use the index of the found color. Otherwise, API will create new thread color with supplied color, value, code, brand and description in the palette of the design, and the corresponding stop of the lettering object will use the index of the new thread color.

For the design has more than 1 colorways, the editDesign/editDesignTrueview only works on one colorway: appointed colorway (by colorway of design) or current colorway (no colorway appointed).

Recolor

<recolor>
   <colorway name=”xxxx”>
      <threads>
         <thread color="32768" code="xx" brand="xx" description="xx" />
         <thread color="1554175" code="xx" brand="xx" description="xx" />
      </threads>
   </colorway> 
</recolor>

The recolor element is used to replace colorways in or add colorways to an existing design. Design colorway and stop sequence information can be retrieved via designInfo or designTrueview APIs. The colorway element is described in the Design Information section under ‘Colorway information’. Only the threads elements and name attribute work with recolor. The current attribute works with the AddColorway option.

Recolor element usage

The recolor element can be used by following APIs:

ReplaceColorway option

The ReplaceColorway attribute option uses the following syntax…

<recolor option="ReplaceColorway">

This option allows you to replace colors in an existing colorway. For example…

<design file="<Filename>.EMB">
  <recolor option="ReplaceColorway">
    <colorway bkg_color="13401855" current="true" name="Colorway 1" >
      <threads>
        <thread color="39168" code="1" brand="Default" description="Dark Green" />
        <thread color="16711680" code="2" brand="Default" description="Blue" />
      ...
      </threads>
    </colorway>
  </recolor>
</design>

Notes:

  • For backwards compatibility, the default option is always ‘ReplaceColorway’ if the attribute is missing from the statement.
  • Use recolor.colorway.name to specify the colorway to be replaced. If it is missing and the design only has one colorway, this will be replaced.

The colors in the colorway will be as provided in the threads list unless:

  • The color index which is used by the design is out of range of the provided thread list. The EWA will append colors from original design to the colorway by position until it reaches the last used color.
  • The provided thread list contains too many colors. Only first 128 colors will be used in any colorway.

AddColorway option

The AddColorway attribute option uses the following syntax…

<recolor option="AddColorway">

This option allows you to add colorways to an existing design. For example…

<design file="<Filename>.EMB">
  <recolor option="AddColorway">
    <colorway bkg_color="13401855" current="true"  name="Colorway 2">
      <threads>
        <thread color="39168" code="1" brand="Default" description="Dark Green" />
        <thread color="16711680" code="2" brand="Default" description="Blue" />
        ...
      </threads>
    </colorway>
  </recolor>
</design>

Notes:

  • The name of the colorway must be provided. If not, an ‘ERROR_INVALID_CWY_NAME’ exception is shown.
  • If a colorway with the specified name already exists, an ‘ERROR_DUPLICATE_CWY_NAME’ exception is shown.
  • If the ‘current’ flag is set to true, the newly added colorway set as current.

Action order

Recoloring is the first action to be undertaken on the API side. The action order is important in some circumstances. As we know, lettering object colors can be modified. If recolor is used at the same time, the action order will affect the color palette of the resulting design. For example…

  1. A design has color palette employing Colors 1 to 8.
  2. The editDesign API is used to change a lettering object to Color 9.
  3. At the same time, recolor provides a list of colors containing Color 9.

If recolor is performed first, the color palette will be modified accordingly and the new color added. The lettering object action is then performed. Color 9 is already in the palette and can be used.

If, on the other hand, the lettering object action is performed first, Color 9 is not yet in the palette so is appended. Then, if the recolor action is performed, it replaces the first 8 colors in the palette. The results will differ.


Lettering

<lettering> 
   <simple_lettering . . .  />		// the simple lettering parameters
   <transform  . . .  />
   <thread  . . .  />
</lettering>

The lettering decorations are specified by the simple_lettering component and the thread component.

Simple Lettering

<simple_lettering 
     text="Lettering 1" 		// the text
     alphabet_name="London" 	        // the alphabet name
     height="20.0" 			// height in mm, min 5.0, max 50.0
     bold="false" 			// bold or not
     italic="false" 			// italic or not
     word_spacing="0.6"		        // word spacing as ratio of height
     justification="centre"		//multi-line text justification
     baseline="horizontal" 		// horizontal, circle_cw,
              			        // circle_ccw, vertical
               			        // horizontal_fixed, vertical_fixed
     baseline_radius="50.0" 		// in mm, for circle baselines
     baseline_length="100.0"		// in mm, for fixed baselines
     auto_fit_mode="spacing"	        // spacing, letter, letter_prop, 
               			        // whole, whole_prop
/>

The simple_lettering component describes the lettering parameters, such as font face, font size, bold, italic, and the baseline.

The alphabet_name parameter specifies the embroidery font face, known as the alphabet. It can only be one of the supported embroidery alphabets installed with the API.

The text parameter specifies the text of the lettering. It can contain multiple lines.

The height parameter is specified in mm. Valid range is from 5.0 to 50.0 mm.

The bold parameter is a Boolean that specifies whether the font should be bold or not. Its value can be either “true” or “false”

The italic parameter is a Boolean that specifies whether the font should be italic or not. Its value can be either “true” or “false”.

The word_spacing parameter specifies the space between words in the supplied text, ie distance occupied by the “space” character. The value is specified as a proportion of the lettering height, eg 0.6 specifying 60%.

The justification parameter string specifies the alignment of text. This is used only when the text contains multiple lines. The allowed values are “left” (left-aligned text), “right” (right-aligned text), “centre” (centred text) and “fit” (fully justified text).

The baseline parameter string specifies the baseline for the lettering object. It can be one of “horizontal”, “vertical”, “circle_cw” (circle clockwise), “circle_ccw” (circle counter-clockwise), “horizontal_fixed” or “vertical_fixed”.

For non-fixed baselines, the size of the resulting lettering cannot be specified upfront, and the text takes up whatever size is necessary for the individual letter sizes and spacings. However, the fixed baselines allow specifying the baseline_length, which in turns constrains the resulting lettering within that size. This guarantees that the lettering will not exceed the size supplied, irrespective of how many letters are in the text parameter, at the expense of possibly reducing the individual letter sizes and / or spacing.

The baseline_radius parameter specifies the radius of the circular baselines. It is ignored for other baselines. The value is in mm and the valid values are 20-1000mm.

The baseline_length parameter specifies the length of the fixed baselines. It specifies the width of the “horizontal_fixed” baseline, or the height of the “vertical_fixed” baseline. The parameter is ignored for non-fixed baselines. The value is in mm and the valid values are 20-1000mm.

The auto_fit_mode parameter specifies the constraining mode for the fixed baselines. It can be one of the following 5 values:

  • “spacing” – Letter Spacing is adjusted, but the letters do not change size.
  • “letter” – Letter Width (for “horizontal_fixed” baseline) or Letter Height (for “vertical_fixed” baseline) is reduced, but Spacing is unchanged.
  • “letter_prop” – Letter Width and Height are reduced proportionally, but Spacing is unchanged.
  • “whole” – Spacing and Letter Width (for “horizontal_fixed” baseline) or Letter Height (for “vertical_fixed” baseline) are reduced.
  • “whole_prop” – Spacing and Letter Width and Height are reduced proportionally.

Team Name Lettering

<team_name_lettering>
   <transform... />
      <simple_lettering... />	// lettering parameters(“text” is ignored)
      <thread... />			// default thread for all team names
      <team_name_options... />	// additional team  name options
      <team_names... />		// specification of each team name
</team_name_lettering>

The team name lettering decoration is specified by a team_name_lettering component. There can only be one team_name_lettering decoration in the whole specification.

As all other components, the team_name_lettering supports a transform.

The simple_lettering component specifies the lettering parameters of the Team Name Lettering objects. The text attribute of the simple_lettering is ignored for team name lettering, as the text for individual team name members is specified in greater detail by the team_names.

The thread component specifies the default thread for each generated team name lettering object. However, it can be optionally overridden with another thread for any particular team_name if specified.

The team_name_options component specifies additional team name lettering options. The team_names component specifies the individual team names.

Team Names

<team_names>			// specification of each team name
   <team_name 			// team name 1
      name1="aa" 		// team name1's column 1 text
      name2="bb" 		// team name1's column 2 text
      name3="cc" 		// team name1's column 3 text
   />
   <team_name 			// team name 2
      name1="dd" 
      name2="ee" 
      name3="ff" >
      <thread... />		// optional specifying special thread for this
                                // particular team name
               
   </team_name>			// team name 3, etc
   <team_name 
      name1="hh" 
      name2="ii" 
      name3="jj" 
   />
</team_names>

The team_names specifies a list of required team names.

Each team_name specifies the text of the lettering object by means of 3 sub-names: name1, name2 and name3. The actual text is obtained by concatenating the 3 names using a space as the separator. The typical usage for the names is to correspond to the first name, middle name, and last name of a person. Each of the names is optional, and in fact the whole text (with spaces) can be specified in any single sub-name, and the others left blank. However, the splitting of the text to sub-names allows further control of individual column’s parameters, eg allowing to make all last names have greater height than the first names.

Additionally, each team_name can optionally specify its own thread, if it is required to be different to the default thread specified as part of the team_name_lettering. If the team’s name-specific thread is not specified, the default thread will be used for that team name.

Team Name Options

<team_name_options 
   name1_height="1.0" 			 // height of the first column
   name2_height="1.0" 			 // height of the second column
   name3_height="1.0" 			 // height of the third column
   output="single_design_team_lettering" // single or multiple design output
/>

The team_name_options component specifies additional team name lettering options.

These options contain specification of the individual heights for each of the team name columns: name1_height, name2_height & name3_height. These are specified as a ratio to the default team lettering height, eg a value of 1.2 would specify 120%.

Additionally, the team name options specify the type of output required for the final team name design. The possible values are “single_design_team_lettering” and “multiple_designs”.

When “single_design_team_lettering” is used, the output will be a single EMB file that includes the whole team name lettering Wilcom ES object with multiple names. This single file will then have to be post-processed by high-level Wilcom ES software for production purposes. This is the output type recommended for the clients that own Wilcom ES software, because of greater possibilities of post-processing depending on the production needs. The other clear advantage is that of only having to manage a single file.

The “multiple_designs” option allows to produce multiple production-ready EMB designs that do not need to be further post-processed. Such designs can then be loaded into low-level Wilcom TrueSizer software for production. This option is recommended for clients that do not own Wilcom ES software.

The names of the multiple files produced with the “multiple_designs” option are auto-generated from the trueview_file and design_file parameters, by means of appending the 1-based team name index to the filename. E.g. if 3 team names are supplied and the design_file specifies “design.emb”, the files generated will be “design1.emb”, “design2.emb” & “design3.emb”, corresponding to the team names 1, 2 and 3 respectively.

Note that the “multiple_designs” option is a superset of the “single_design_team_lettering”, in that the single team lettering design is still produced as well. It is also a more resource-intensive option.

Monogram

<monogram>
   <monogram_lettering... />		// the Lettering component of Monogram
   <monogram_ornament... />		// the Ornament component of Monogram
   <transform... />			// as above
</monogram>

The monogram contains two components, the lettering, specified by monogram_lettering and the ornament set, specified by monogram_ornament.

An optional transform is supported.

Monogram Lettering

<monogram_lettering 
   text="abc"				// the text 
   style="style_01"			// the initials layout style
   alphabet_name="Block2"		// the alphabet name
   height="12">			        // lettering height, in mm
   <thread .../>			// monogram lettering thread
</monogram_lettering>

The monogram_lettering component specifies the lettering object inside the monogram.

The style string must be in the form of “style_01”, “style_02”, etc. up to “style_23”, specifying one of 23 layout styles supported by Wilcom ES Monogram:

For backward compatibility, the style name is same as Embroidery Studio E3.   Embroidery Studio E4 display the icons in its GUI in following order:

  1. style_05
  2. style_04
  3. style_06
  4. style_01
  5. style_09
  6. style_23
  7. style_07
  8. style_17
  9. style_08
  10. style_18
  11. style_02
  12. style_03
  13. style_19
  14. style_20
  15. style_21
  16. style_22
  17. style_11
  18. style_10
  19. style_12
  20. style_13
  21. style_14
  22. style_15
  23. style_16

You can use same order if you want to match your GUI to Embroidery Studio E4 GUI.

As with simple lettering, the height specifies the height of the text in mm, and the alphabet_name specifies the embroidery font. The thread specifies the thread for the monogram lettering. There is a limitation to specify color for some special alphabets that have letters with saved colors/functions, see Letters created with unchecked remove functions.

Monogram Ornament

<monogram_ornament
   is_motif="true"			// motif or file
   alphabet_name="01Monogram Ornaments"	// motif alphabet name
   name="M001a"				// motif or file name
   width="0"				// width of ornament (or 0 for default)
   height="0"				// height of ornament(or 0 for default)
   style="duplicates">			// ornament style
   <transform... />			// ornament transform, scale not used
   <positions>				// ornament positions
      <position>top_centre</position>
      <position>centre_left</position>
      <position>centre_right</position>
      <position>bottom_centre</position>
   </positions>
   <thread .../>			// monogram ornament thread
</monogram_ornament>

The monogram_ornament component specifies the ornament set inside the monogram. The ornament set is comprised of an ornament repeated in a number of positions around (or under) the monogram lettering. The ornament can be specified from either a motif or an embroidery file, which is controlled by the is_motif.

  • If the ornament is a motif, then the alphabet_name specifies the motif embroidery alphabet, and the name specifies the motif name.
  • If the ornament is a filename, then the name should specify the filename, and the alphabet_name is ignored. The file content is base64 encoded in files element.

The width and height of the ornament can optionally specify the desired size to scale each ornament before positioning it. Specifying zero for both height and width will leave the ornament unscaled.

The ornament style specifies an additional layout style for ornaments, and can be either of “mirrors”, “duplicates” or “cycle”.

The transform specifies the remaining ornament transform, again applied to each ornament before positioning it. As the width and height already specify the optional scaling width and height, the scale parameter of the transform is ignored. The dx parameter specifies the distance from lettering, and for all but the “centre_centre” positions, the dy parameter is ignored.

A list of positions specifies the positions of ornaments in the ornament set around the monogram lettering. There are 9 possible positions: “top_left”, “top_centre”, “top_right”, “centre_left”, “centre_centre”, “centre_right”, “bottom_left”, “bottom_centre” and “bottom_right”. The thread specifies the thread for the monogram ornament set.

Output

<output
   trueview_file="final_design_trueview.png"
   design_file="final_design.emb"	// for GenerateDesign only
   design_version=""			// optional design version
   dpi ="120"				// optional dpi of turview

/>

The output component specifies the output of the function.

The trueview_file parameter is a filename identifier for the resulting TrueView™ preview bitmap. It is compulsory for api/newDesignTrueview and api/newLetteringPreview functions and is optional for api/newDesign function.

The design_file parameter is a filename identifier for the resulting final embroidery design. It is compulsory for api/newDesign function. It is ignored for api/newDesignTrueview and api/newLetteringPreview functions.

The EWA doesn’t support Unicode in output filename now. So, it limits that only 0-9, a-z, A-Z, “-“, “_” and space are allowed in the filename part of trueview_file and design_file .  An error with useful information will be returned if client uses unsupported characters.

The design_version parameter is a string that optionally specifies the version for the design file saved. If the design_version is absent, or is specified as empty, the latest version of the design file is saved (e4.5).

The allowed version strings are changed in EWA4.5 to match those from the formats list in the “Save As” dialog of the English language Wilcom ES software. For example,

  • “Wilcom All-in-One Designs 27.0 (Digital Edition) (*.EMB)” specifies saving in 2025 format
  • “Wilcom All-in-One Designs 26.0 (Digital Edition) (*.EMB)” specifies saving in Digital Edition format
  • “Wilcom All-in-One Designs e4.5 (*.EMB)”                specifies saving in e4.5 format.
  • “Wilcom All-in-One Designs e4.2 (*.EMB)”                specifies saving in e4.2 format.
  • “Wilcom All-in-One Designs e4.1 (*.EMB)”                specifies saving in e4.1 format.
  • “Wilcom All-in-One Designs e4.0 (*.EMB)”                specifies saving in e4 format.
  • “Wilcom All-in-One Designs e3.6 (*.EMB)”                specifies saving in e3.6 format (version of .EMB created for Hatch home software).
  • “Wilcom All-in-One Designs e3.5 (*.EMB)”                specifies saving in e3.5 format (version of .EMB created for Hatch home software).
  • “Wilcom All-in-One Designs e3 (*.EMB)”                  specifies saving in e3 format.
  • “Wilcom All-in-One Designs e2 (*.EMB)”                  specifies saving in e2 format.

Saving back to earlier versions of .EMB is not supported, as is the case in Wilcom ES Software version e4/4.1.

The design version string must match the extension specified in design_file. The design version can only be specified for Wilcom native formats like .EMB. It cannot be specified for stitch formats like .DST. The dpi parameter is an integer, specified the dpi of resulting image. Default value is 96. Default value will be use if it is missing or equal or less than 0. The Max value is 300.

Bitmap Recipe: bitmap XML Data

<bitmap 
   file=”logo.jpg”
   remove_background="true"
/>

Usage:

The bitmap xml string is used in:

The bitmap file is specified by file. The file content is located in files identified by filename.

The remove_background option informs EWA if detect and remove the background. Default value is true. This option is ignored if original bitmap is already transparent. The bitmap is trivial now. More parameters may be added here in future.

Source Bitmap Recipe: source_bitmap_info XML Data

<source_bitmap_info 
   transparent=”false” 
/>

Usage:

The source_bitmap_info xml string is used in:

The source_bitmap_info contains the information about source bitmap image. The transparent is set as true if input bitmap already has transparent pixels.

Vector Recipe: vector XML Data

<vector 
   file=”logo.pdf”
   dpi=96
   remove_background="true"
/>

Usage:

The vector xml string is used in:

The vector file is specified by file. The file content is located in files identified by filename.

The client can assign dpi to have EWA to generate different quality of preview from vector file. The dpi value must be between 0 and 480. The default value is 96 if the dpi is missing or its value is 0.  The parameter is only useful for api/vectorArtPreview.

Sometimes vector file only contains bitmap file or has a vector object as background, so EWA does further processing after converting to PNG as bitmapArtPreview by default. This behaviour can be controlled by remove_background option. Default value is true.

Auto Digitize Options Recipe: autodigitize_options XML Data

<autodigitize_options 
   width = “100”
   height=”100”
   thread_file=”threadchart.tch”	// Thread chart file name, the file
                                        // content is in files element
>
   <threads>				// list of nominatied thread colors
      <thread... />
      <thread... />
      <thread... />
   </threads>
</autodigitize_options>

Usage:

The autodigitize_options xml string is used in:

Both width and height are optional.

The image dpi will be used to calculate result design size if both are not provided. Be careful when using DPI, we have experience that some images have no DPI or DPI is hidden. Or DPI is different when opening it in different software like Irfanview, .NET library or ImageMagick.  EWA choose .NET library as standard which is same as the value seen in the file property dialog under windows. The default DPI is 96 is image has no DPI or DPI is hidden.

The other side will be calculated to maintain aspect ratio if either of them is provided. 

If both are provided, the result design will just fit in the appointed rectangle without losing aspect ratio.

Loss of precision is not possible to avoid when calculating between inch, DPI and millimetre, so the result design size is slightly different from appointed width and height parameter.

thread_file is optional. It specifies a thread chart file (.tch). API will use the colors in this chart when processing auto-digitizing. The thread chart file itself must be supplied in the list of files with same name.

<threads> is optional. It specifies nominated thread colors which will be used in result design. 

The <threads> takes precedence over the thread_file if both exist.

At first, EWA processes — like colors reduction, etc – the image artwork to make it available for auto digitizing. Then

  • If <threads> or thread_file has values, match the colors to the nominated thread colors.
  • If <threads> and thread_file are empty or absent, the API try to search the color RGB value of processed image in the default color palette. If the exact color is found use it otherwise append the color to the default palette without code, brand and description.

At last, generate the stitches.

Supported formats

There are a few supported formats. They have been outlined in below links.

Embroidery formats

Embroidery formats

This table list all embroidery design formats supported as Input and output. 

FormatDescriptionInputOutputNotes for Output
.EMBWilcom all-in-one Design fileYesYesOnly ES e2 and above versions are supported as output.
.EMCWilcom Clipart fileYesYes 
.EMTWilcom Template fileYesYes 
.EMXWilcom Cross Stitch fileYesNo 
.U??Barudan fileYesYes 
.TAPHappy fileYesYesThe following additional files are returned as well: * MON: Header data * HP1: Needle number data
.INBInbro fileYesYes 
.EXPMelco fileYesYesThe following additional files are returned as well: * INF: Color info * BMP: Design icon bitmap
.KSMPfaff fileYesYes 
.DSBBarudan fileYesYes 
.DSTTajima fileYesYesThe following additional files are returned as well: * DGT: Design icon bitmap * BMP: Chenille (Additional data for Tajima Chenille machines) * LT0: TBF supporting information
.DSZZSK fileYesYes 
.TBFTajima fileYesYesThe following additional files are returned as well: * CT0: Condition file * DGF: Design icon bitmap
.10OToyota fileYesYesThe following additional files are returned as well: * 00O: Header data
.Z??ZSK TC fileYesYes 
.PESDeco/Brother/Babylock fileYesYes 
.XXXSinger fileYesYes 
.HUSHusqvama/Viking fileYesYes 
.JEFJanome/Elna/Kenmore fileYesYes 
.ARXArtista Cross Stitch fileYesNo 
.T01Tajima – Wilcom DST format fileYesYes 
.T03Barudan – Wilcom DSB format fileYesYes 
.T04Zangs fileYesYes 
.T05ZSK – Wilcom DSZ format fileYesYes 
.T09Pfaff – Wilcom KSM format fileYesYes 

Bitmap formats

Bitmap formats

This table list all bitmap file formats supported as Input.

FormatDescriptionNotes for Output
.JPG
.JPEG		Joint Photographic Experts Group 
.BMPMicrosoft Windows bitmap 
.PNGPortable Network Graphics 
.GIFGraphics Interchange Format 
.PSDAdobe Photoshop bitmap file 
.TIFTagged Image File Format 

Vector formats

Vector formats

This table list all vector file formats supported as Input.

FormatDescriptionNotes for Output
.EPSAdobe Encapsulated PostScript 
.PDFPortable Document Format 

Limitations

Request size

The API only accepts the request which size is less than 20MB.

Auto digitize limitations

The artwork for auto digitizing couldn’t be processed in reasonable time if it is too big. And they also consume too much server resource. So the EWA set up following restrictions:

LimitationValueNote
Maximum file size2MB 
Maximum pixel count5,000,000 pixelsFor vector file, EWA calculates pixel count in 300DPI.
Maximum area size22,500 square millimetres 
Maximum processing time90 seconds 

Usage:

The auto digitize limitations are used in following API:

API Developer Guide

Introduction

This document provides step by step instructions to help developers get started using Wilcom Embroidery Web API.

Sign Up as a Developer on Wilcom API Developer Portal

Your company must first sign up as a developer on the Wilcom Developer Portal, https://developer.wilcom.com, and select an API plan.

Commercial details should be made with your company’s local Wilcom distributor.

Read the Documentation about the API

Sign in to the API developer Portal, and read the documents supplied there on the Documentation Page. The “Wilcom Embroidery Web API Product Description” document describes the conceptual architecture of the system and the embroidery functionality it can provide.

Get Application Id and Key from API Developer Portal

To get the application Id and key, you have to sign in the Developer Portal.

Navigate to the applications page:

You will see a default application and its Application  Id in a table. See the application key by clicking view button at right of an applications.

  • You can optionally create multiple application keys for your application if you wish, but this is not recommended.
  • Optionally specify an IP address to restrict use of your application to selected referrer addresses.
  • If you want to Review or change the API Plan for your application, consult your company and make a request to Wilcom through the portal here.
  • Your application state will be pending until it is approved.

Edit the Details of Your Application

  • Edit the application name to match your intended use for your application.
  • Edit the description of your application to explain what it does in user terms.

Calling Embroidery Web API Service

Embroidery Web API is a Restful API.

How to Call the API

Consume EWA is very simple. Just send request to the urls with appropriate post parameters. The API will return string which format is xml. The http status code of response is 200.

The http status code will not be 200 if exception occurs when API processing the request. The error information is returned too. Refer to the Embroidery Web API Interface Spec document.

URL for the API Service

Access the API at URL are as below:

https://public.ewa.wilcomapps.com/ – this URL address is for general API calls

https://public.ewa.wilcomapps.com/ – this URL is only for Autodigitizing calls (i.e., bitmapArtDesign, vectorArtDesign, bitmapArtTrueview, vectorArtTrueview)

APIs

It contains following APIs now:

URL to address below API calls – http://ewa.wilcom.com/4.5

  • api/info
  • api/designInfo
  • api/designTrueview
  • api/newDesignTrueview
  • api/newDesign
  • api/editDesignTrueview
  • api/editDesign
  • api/newLetteringPreview
  • api/bitmapArtPreview
  • api/vectorArtPreview

URL to address below API calls – http://ewa.wilcom.com/4.5a

  • api/bitmapArtDesign
  • api/vectorArtDesign
  • api/bitmapArtTrueview
  • api/vectorArtTrueview

Refer to the Embroidery Web API Interface Spec document which describes the web methods and their parameters in detail.

You must use your application Id and application key when calling an API web method.

RestSharp Library (.NET)

It is not straightforward to call Restful API from C# client. Fortunately, there is an open-source library to help: RestSharp (http://restsharp.org/).

We did some small changes to fit the EWA. You can download our version from the Documentation page on the API Developer Portal.

The library is based on .NET framework 4 and source code is managed by visual studio 2010 projects. Please download and modify the source code following the readme.txt to compile yours if you are using different .NET framework version.

Obtain the library

Download the sample source from the Documentation page on the API Developer Portal.

Get RestSharp.dll.

Or open WilcomRestSharp.sln in your visual studio 2010 then rebuild the DLLs.

The DLLs are .NET 4 assemblies. Please build from source code if you are working on earlier version of .NET framework.

EWA XML Source Library (.NET)

Wilcom provides EWA XML Source Library (.NET) to help the converting between xml string and objects. The library is based on .NET framework 4 and source code is managed by Visual studio 2010 projects.

Source is provided for .NET. Other languages will be supplied in future. Request your preferences.

The parameters of API are pretty simple: application id, application key and xml string. The format of xml string is defined in XML Data Package Definitions section in Embroidery Web API Interface Spec document.

Obtain the library

Download the sample source from the Documentation page on the API Developer Portal.

Get Wilcom.EWAEntity.dll and Wilcom.GeneralEntity.dll.

Or open EWAXmlLibrary.sln in your visual studio 2010 then rebuild the DLLs.

The DLLs are .NET 4 assemblies. Please build from source code if you are working on earlier version of .NET framework.

Import the library into your source code

Reference both Wilcom.EWAEntity.dll and Wilcom.GeneralEntity.dll in your project.

Import the name space in you source code.

using Wilcom.API.RecipeManager;

Use the library

Here is an example how to construct an xml string for lettering, then calling WILCOM_GenerateTrueview and paring the result xml string to object. Saving the generated trueview to Result.png at last.

XmlEWARecipe recipe = new XmlEWARecipe()
{
    recipe = new XmlKioskDocument()
    {
        decorations = new List<decoration>()
        {
            new lettering()
            {
                simple_lettering = new simple_lettering()
                {
                    alphabet_name = "Block2", 
                    text = "My Lettering", 
                    height = 20f 
                },
                thread = new thread()
                {
                    color =  Color.Red.R | Color.Red.G << 8 | Color.Red.B << 16 
                }
            }
        },
        output = new output()
        {
            trueview_file = "ResultImage.png",
        }
    }
};

string xmlRecipeString = StringXmlSerializer.FastSerialize<XmlEWARecipe>(recipe, StaticXmlSerializers.GetSerializer<XmlEWARecipe>(null));
	var client = new RestClient("https://public.ewa.wilcomapps.com/");

       var request = new RestRequest("api/newdesigntrueview", Method.POST);
       request.AddParameter("appId", EWADeveloperAppId);
       request.AddParameter("appKey", EWADeveloperAppKey);
       request.AddParameter("RequestXml", xmlRecipeString);

       IRestResponse httpResponse = client.Execute(request);

       if (httpResponse.StatusCode == HttpStatusCode.OK)
       {
XmlEWAResponse response = StringXmlSerializer.FastDeserialize<XmlEWAResponse>(httpResponse.Content, StaticXmlSerializers.GetSerializer<XmlEWAResponse>());
              
byte[] result= Convert.FromBase64String(response.files[0].filecontents);
              File.WriteAllBytes("Result.png", result);
         }
↑ Back to top
!