Using XML to describe designs¶

Examples¶

Two designs

Download

<?xml version="1.0" encoding="UTF-8"?>
<sculpteo>

    <design>
        <name>Petit Boudha</name>
        <description>One of our test models.</description>
        <model href="Petit_Boudha.3ds" />
        <unit>cm</unit>
        <!-- This model can be only ordered in two sizes: real size, and half size -->
        <sizes>
            <scale>1</scale>
            <scale>0.5</scale>
        </sizes>
    </design>

    <design>
        <name>Amortisseur</name>
        <description>Another test model.</description>
        <!-- This model may be fragile, restrict choices of materials to strong ones -->
        <materials>
            <material>white_plastic</material>
            <material>black_plastic</material>
            <material>red_plastic</material>
            <material>green_plastic</material>
            <material>yellow_plastic</material>
            <material>blue_plastic</material>
        </materials>
        <model href="Amortisseur.3ds" />
    </design>

</sculpteo>

A simple design with an external reference

Download

<?xml version="1.0" encoding="UTF-8"?>
<sculpteo>
    <design>
        <name>Stairs</name>
        <description>This is a design from Google 3D Warehouse.</description>
        <model src="http://www.cc.gatech.edu/data_files/large_models/bunny.ply.gz"/>
    </design>
</sculpteo>

A scripted customizable cup

Download

<?xml version="1.0" encoding="UTF-8"?>
<sculpteo>

    <design configurable="1">
        <name_en>Customizable Cup</name_en>
        <name_fr>Tasse personnalisable</name_fr>
        <description_en>A cup of customizable shape.</description_en>
        <description_fr>Une tasse de forme modifiable.</description_fr>
        <model src="tasse.obj" />

        <operation type="script">
            <script src="tasse_mod.js" locked="1" />

            <parameter type="slider" value="0.3">
                <description_en>Shape</description_en>
                <description_fr>Forme</description_fr>
                <bind value="dx" />
            </parameter>

        </operation>
    </design>

</sculpteo>

List of supported tags¶

The following tags are supported in the Sculpteo XML File Format. For each tag, the potential parents and children are listed. Some tags may have attributes which are either optional or mandatory. Although XML attribute values are always strings, they may be used to represent other types of information, such as boolean (bool), integer (int), floating point number (float), in which case the expect type of information is also documented. In any case, the string representation of the value is used (e.g. “0.5” for a floating point number, “42” for an integer, “true” for a boolean). For the boolean type, “1”, “true” or the name of the attribute is intepreted as a true value, all other values are interpreted as a false value.

<sculpteo>

This is the root tag. It is used to identify the XML file as a Sculpteo XML file. It may contain any number of <design> tags.

children

<design>

<design>

This tag describes a single design. It may contain any number of children tags used to provide information on the design.

parent

<sculpteo>

children

<name>, <name_en>, <name_fr>, <description>, <description_en>, <description_fr>, <operation>, <unit>, <scale>, <sizes>

attributes

• configurable (optional, bool): indicates that this is a configurable design

<name>,<name_en>,<name_fr>

Contains the name of the design. The _en and _fr variants of the tags may be used to provide a localized name. Otherwise the same name is used in all languages.

parent

<design>

<description>,<description_en>,<description_fr>

Contains the description of the design or configuration parameter. The _en and _fr variants of the tags may be used to provide a localized description. Otherwise the same description is used in all languages.

parent

<design>, <parameter>

<unit>

Contains the unit of the model. Must be one of ‘mm’, ‘cm’, ‘m’, ‘ft’, ‘yd’ or ‘in’. Defaults to ‘cm’. One unit in the model equals to the unit selected.

parent

<design>

<scale>

Float defining a scale of the model (1 for original scale)

• if child of <design>, default scale for the model. If it’s not provided, defaults to 1 (if it’s an eligible scale for the model, meaning not too little/too big for 3D print).

• if child of <sizes>, a fixed scale. The user will then be presented a list of possible sizes at order.

parent

<design>, <sizes>

<sizes>

List of scales at which the model can be ordered. If not present, user is free to choose the size he wants.

parent

<design>

children

<scale> (mandatory)

<materials>

List of materials in which the model can be printed. If not present, user is free to choose the material he wants.

parent

<design>

children

<material> (mandatory)

<material>

A material to choose among those available. List of available materials is listed here: WorkFlow.

parent

<materials>

<model>

The 3D model of the design. The model must be in one of the formats supported by Sculpteo. It may also be an archive containing the 3D model and its associated textures. In case an url is provided, the file is downloaded from that url at upload time.

parent

<design>

attributes

• src (mandatory, string): the filename or url of the 3D model

<operation>

This tag is used to describe a modifying operation on a design. A design may contain multiple <operation> tags, in which case the modifications are made in the order they appear in the XML file. The “type” attribute indicates which kind of modification is made to the design, and may be one of “color”, “text” or “script”. Each operation and operation parameter may be modified by other users if the design is configurable, unless the operation or parameter is locked. The “locked” attribute is used to indicate which field may be modified, and is inherited by children tags. The default is unlocked. The “color” operation type changes the color of 3D model globally. A color gradient may also be specified by providing two colors and a 3D direction. The “text” operation type adds a 3D text at the surface of the design, at a position chosen by the user or indicated by the children tags. The text, font and size may be specified by children tag. The 3D text may also be carved instead of added to the model. The “script” operation type modifies the design according to a script and optional parameters provided in children tags.

parent

<design>

children

<color>,<gradient>,<direction>,<position>,<rotation>,<text>,<font>,<dig>,<size>,<height>,<script>,<parameter>

attributes

• type (mandatory, string): the type of operation

• locked (optional, bool): prevent operation modification during configuration

<color>

Used to describe a color in the RGB colorspace. If this parameter is modifiable, a color picker is presented to the user during configuration.

parent

<operation type=”color”>, <operation type=”text”>, <gradient>

attributes

• rgb (mandatory, string): the color in HTML format (e.g. #ff0000 for red)

• locked (optional, bool): prevent parameter modification during configuration

<gradient>

Used to describe a color gradient in the RGB colorspace. If this parameter is modifiable, it may be disabled in which case only the first color is used. This tag must contain two <color> children and a <direction> child indicating the direction in 3D space in which the linear color gradient is applied. The first vertex of the model along the chosen direction is colored with the first color, while the last vertex along the chosen direction is colored with the second color.

parent

<operation type=”color”>

children

<color>,<direction>

attributes

• locked (optional, bool): prevent parameter modification during configuration

<direction>

Indicates a direction in 3D space.

parent

<gradient>,<operation type=”text”>

attributes

• x (mandatory, float): X-coordinate of the direction vector

• y (mandatory, float): Y-coordinate of the direction vector

• z (mandatory, float): Z-coordinate of the direction vector

• locked (optional, bool): prevent parameter modification during configuration

<position>

Indicates a position in 3D space.

parent

<operation type=”text”>

attributes

• x (mandatory, float): X-coordinate of the position vector

• y (mandatory, float): Y-coordinate of the position vector

• z (mandatory, float): Z-coordinate of the position vector

• locked (optional, bool): prevent parameter modification during configuration

<rotation>

Describes a rotation in 3D space via a quaternion. For a rotation of axis <X,Y,Z> and angle A, the corresponding quaternion is <cos(A/2),sin(A/2)*X,sin(A/2)*Y,sin(A/2)*Z>.

parent

<operation type=”text”>

attributes

• w (mandatory, float): scalar component of the quaternion

• x (mandatory, float): X-coordinate of the quaternion vector component

• y (mandatory, float): Y-coordinate of the quaternion vector component

• z (mandatory, float): Z-coordinate of the quaternion vector component

• locked (optional, bool): prevent parameter modification during configuration

<text>

Contains the text to be added to the model.

parent

<operation type=”text”>

attributes

• locked (optional, bool): prevent parameter modification during configuration

<font>

Selects with which font to create the 3D text. The “name” attribute is used to select one of the system fonts, or to name the custom font if the “src” attribute is also present. The currently supported system fonts are “Blackjack”, “Coolvetica”, “Delta Hey Max 9”, “Earwig Factory”, “Geometry Soft Pro” (default if no <font> tag is present), “GoodDog”, and “Walkway Expand Black”. If present, the “src” attribute indicates to use a custom font provided as a TTF or SVG font file.

parent

<operation type=”text”>

attributes

• name (mandatory, string): the name of the font

• src (optional, string): filename or url of the font

• locked (optional, bool): prevent parameter modification during configuration

<dig>

Used to indicate that the 3D text is carved (difference) instead of added (union) to the 3D model.

parent

<operation type=”text”>

attributes

• value (mandatory, bool): carve the text instead of adding it

• locked (optional, bool): prevent parameter modification during configuration

<size>

Used to indicate that the 3D text size.

parent

<operation type=”text”>

attributes

• value (mandatory, float): text size

• locked (optional, bool): prevent parameter modification during configuration

<height>

Used to indicate that the 3D text height.

parent

<operation type=”text”>

attributes

• value (mandatory, float): text height

• locked (optional, bool): prevent parameter modification during configuration

<script>

Contains the modification script. The only language supported is Javascript. The available objects and API is described in Using JavaScript for scripting designs. The script may either be inlined in the tag, in which case it should be enclosed with “/* <![CDATA[ */” and “/* ]]> */” to prevent XML parsing errors. Optionally, it may be read or downloaded from an external resource given by the “src” attribute.

parent

<operation type=”script”>

attributes

• src (optional, string): filename or url of the script

• locked (optional, bool): prevent script modification during configuration

<parameter>

Describes a script parameter. The “type” attribute is used to select among various parameter types, such as “text”, “slider”, “select”, or “texture”. The “value” attribute may be used to provide a default value to the parameter. Parameters may (and should) be bound to Javascript variables via the “<bind>” child tag. A description may be presented to the user during configuration via the “<description>” child tag or its localized variants.

• the “text” parameter type presents a text field to the user and contains a string value. Parameters of the “text” type are represented via Javascript Strings when bound.

• the “slider” parameter type presents a slider to the user and contains a float value, constrained in [‘min’,’max’] (default [0.0,1.0]). Parameters of the “slider” type are represented via Javascript Numbers when bound.

• the “select” parameter type presents the user with a select box and contains a text parameter. Available options are provided via any number of “<option>” children tags. Parameters of the “select” type are represented via Javascript Strings when bound.

• the “color” parameter type presents a color wheel to the user. Its optional ‘html’ attribute may be used to specify the default color. Alternatively, the ‘red’, ‘green’ and ‘blue’ attributes, optionally abbreviated to ‘r’, ‘g’, ‘b’ respectively, may be used to specify each component independently. Parameters of the “color” type are represented via three Javascript Numbers, each bound to one of the components of the color.

• the “texture” parameter type presents an image. It defaults to its ‘src’ attribute. If not locked, user will be able to change this parameter. Choices may be limited to a texture list via the optional ‘choices’ attribute. Parameters of the “texture” type are represented via “Texture” Javascript objects when bound.

• the “design” parameter type presents a design. If not locked, user will be able to change this parameter, by picking a design in public gallery or in to a design list as indicated via the optional ‘choices’ attribute. Parameters of the “design” type are represented via “Mesh” Javascript objects when bound.

• the “font” parameter type presents a font selector to the user. The ‘name’ attribute may be used to specify a default font. The ‘src’ attribute may be added to use a custom font read from a file or URL. If both ‘name’ and ‘src’ attributes are set, the custom font will be used, and its name will be set to the ‘name’ attribute for display and reuse. Parameters of the “font” type are represented via “File” Javascript objects when bound.

• the “audio” parameter type presents an audio record to the user. The audio data may be recorded or uploaded from a file depending on platform. The ‘src’ attribute may also be used to specify the default audio record. Only WAV file format is supported so far. Parameters of the “audio” type are represented via “Audio” Javascript objects when bound.

parent

<operation type=”script”>

children

<description>,<description_en>,<description_fr>,<bind>,<option>

attributes

• type (mandatory, string): type of parameter

• value (optional, variable): default parameter value

• min (optional, float): minimum value for the “slider” type

• max (optional, float): maximum value for the “slider” type

• locked (optional, bool): prevent parameter modification during configuration

• src (optional, string): filename (must be present in ZIP file) or url for the parameter

• choices (optional, string): UUID of a list of the parameter type, from which to choose the parameter

• name (optional, string): name of the font

• red or r (optional, float): red component of the color

• green or g (optional, float): green component of the color

• blue or b (optional, float): blue component of the color

• html (optional, string): html representation of the color (e.g. #ff0000)

<bind>

Binds the parameter value to a JavaScript variable. The name of the variable is given by the “value” attribute.

parent

<parameter>

attributes

• value (string, mandatory)

<option>

An available choice in the select parameter. The “value” attribute contains the value assigned to the parameter when the option is selected. The text contained in the tag is presented to the user during configuration to describe the option.

parent

<parameter type=”select”>

attributes

• value (string, mandatory)