Difference between revisions of "TG3 File Format"

From TexGen
Jump to navigationJump to search
 
(78 intermediate revisions by 5 users not shown)
Line 1: Line 1:
==Introduction==
+
__NOTOC__
 
The file format for storing TexGen data has the extension TG3 which stands for TexGen v3. It is an XML file where each element usually corresponds to a class within TexGen core. When a TG3 file is saved, there is an option as to how much data is saved:
 
The file format for storing TexGen data has the extension TG3 which stands for TexGen v3. It is an XML file where each element usually corresponds to a class within TexGen core. When a TG3 file is saved, there is an option as to how much data is saved:
  
Line 6: Line 6:
 
* [[#Full|Full]]
 
* [[#Full|Full]]
  
No matter which of the options is chosen TexGen is able to read the data and recreate the exact some model as was originally saved provided files are saved and loaded by the same version of TexGen. Results may vary when loading a file from a different version of TexGen depending on the output type. For example, if the class to represent a specific textile (e.g. CTextileWeave2D) is modified so that the geometry is created in a different way. Files saved from an old version with minimal output will have the new geometry whereas files saved with standard or full output will retain the old geometry.
+
No matter which of the options is chosen TexGen is able to read the data and recreate the exact some model as was originally saved provided files are saved and loaded by the same version of TexGen. Results may vary when loading a file from a different version of TexGen depending on the output type. For example, if the class to represent a specific textile (e.g. CTextileWeave2D) is modified so that the geometry is created in a different way. Files saved with an old version with minimal output will have the new geometry whereas files saved with standard or full output will retain the old geometry.
  
 
===Minimal===
 
===Minimal===
Line 18: Line 18:
  
 
==Structure==
 
==Structure==
The file follows the XML conventions and as such is human readable. Here is an example file:
+
The file follows the XML conventions and as such is human readable. Here is an example file saved with [[#Standard|Standard]] output:
  
    <?xml version="1.0" ?>
+
<?xml version="1.0" ?>
    <TexGenModel version="2.9.0">
+
<TexGenModel version="3.0.0">
        <Textile name="2DWeave(W:2,H:2)" type="CTextileWeave2D" AssignedDomain="Planes(N:6)" NeedsBuilding="0" NumXYarns="2" NumYYarns="2" GapSize="0" FabricThickness="0.2" Refine="0">
+
    <Textile name="2DWeave(W:2,H:2)" type="CTextileWeave2D" NeedsBuilding="0" NumXYarns="2" NumYYarns="2" GapSize="0" FabricThickness="0.4" Refine="0">
            <Yarn index="0" NumSlaveNodes="26" NumSectionPoints="20" NeedsBuilding="7">
+
        <Domain type="CDomainPlanes">
                <Interpolation Periodic="1" type="CInterpolationBezier" />
+
            <Plane Normal="1, 0, 0" d="-0.5" />
                <YarnSection type="CYarnSectionConstant">
+
            <Plane Normal="-1, 0, 0" d="-1.5" />
                    <SectionList index="0" type="CSectionEllipse" NeedsMeshing="1" Width="0.8" Height="0.1" />
+
            <Plane Normal="0, 1, 0" d="-0.5" />
                </YarnSection>
+
            <Plane Normal="0, -1, 0" d="-1.5" />
                <Repeat value="2, 0, 0" />
+
            <Plane Normal="0, 0, 1" d="-0.02" />
                <Repeat value="0, 2, 0" />
+
            <Plane Normal="0, 0, -1" d="-0.42" />
                <MasterNode index="0" Position="0, 0, 0.05" Tangent="0, 0, 0" Up="0, 0, 1" />
+
        </Domain>
                <MasterNode index="1" Position="1, 0, 0.15" Tangent="0, 0, 0" Up="0, 0, 1" />
+
        <Yarn index="0" NumSlaveNodes="25" NumSectionPoints="20" NeedsBuilding="7">
                <MasterNode index="2" Position="2, 0, 0.05" Tangent="0, 0, 0" Up="0, 0, 1" />
+
            <Interpolation Periodic="1" type="CInterpolationBezier" />
            </Yarn>
+
            <YarnSection type="CYarnSectionConstant">
            <Yarn index="1" NumSlaveNodes="26" NumSectionPoints="20" NeedsBuilding="7">
+
                <SectionList index="0" type="CSectionEllipse" NeedsMeshing="1" Width="0.8" Height="0.2" />
                <Interpolation Periodic="1" type="CInterpolationBezier" />
+
            </YarnSection>
                <YarnSection type="CYarnSectionConstant">
+
            <Repeat value="2, 0, 0" />
                    <SectionList index="0" type="CSectionEllipse" NeedsMeshing="1" Width="0.8" Height="0.1" />
+
            <Repeat value="0, 2, 0" />
                </YarnSection>
+
            <MasterNode index="0" Position="0, 0, 0.1" Tangent="0, 0, 0" Up="0, 0, 1" />
                <Repeat value="2, 0, 0" />
+
            <MasterNode index="1" Position="1, 0, 0.3" Tangent="0, 0, 0" Up="0, 0, 1" />
                <Repeat value="0, 2, 0" />
+
            <MasterNode index="2" Position="2, 0, 0.1" Tangent="0, 0, 0" Up="0, 0, 1" />
                <MasterNode index="0" Position="0, 1, 0.15" Tangent="0, 0, 0" Up="0, 0, 1" />
+
        </Yarn>
                <MasterNode index="1" Position="1, 1, 0.05" Tangent="0, 0, 0" Up="0, 0, 1" />
+
        <Yarn index="1" NumSlaveNodes="25" NumSectionPoints="20" NeedsBuilding="7">
                <MasterNode index="2" Position="2, 1, 0.15" Tangent="0, 0, 0" Up="0, 0, 1" />
+
            <Interpolation Periodic="1" type="CInterpolationBezier" />
            </Yarn>
+
            <YarnSection type="CYarnSectionConstant">
            <Yarn index="2" NumSlaveNodes="26" NumSectionPoints="20" NeedsBuilding="7">
+
                <SectionList index="0" type="CSectionEllipse" NeedsMeshing="1" Width="0.8" Height="0.2" />
                <Interpolation Periodic="1" type="CInterpolationBezier" />
+
            </YarnSection>
                <YarnSection type="CYarnSectionConstant">
+
            <Repeat value="2, 0, 0" />
                    <SectionList index="0" type="CSectionEllipse" NeedsMeshing="1" Width="0.8" Height="0.1" />
+
            <Repeat value="0, 2, 0" />
                </YarnSection>
+
            <MasterNode index="0" Position="0, 1, 0.3" Tangent="0, 0, 0" Up="0, 0, 1" />
                <Repeat value="2, 0, 0" />
+
            <MasterNode index="1" Position="1, 1, 0.1" Tangent="0, 0, 0" Up="0, 0, 1" />
                <Repeat value="0, 2, 0" />
+
            <MasterNode index="2" Position="2, 1, 0.3" Tangent="0, 0, 0" Up="0, 0, 1" />
                <MasterNode index="0" Position="0, 0, 0.15" Tangent="0, 0, 0" Up="0, 0, 1" />
+
        </Yarn>
                <MasterNode index="1" Position="0, 1, 0.05" Tangent="0, 0, 0" Up="0, 0, 1" />
+
        <Yarn index="2" NumSlaveNodes="25" NumSectionPoints="20" NeedsBuilding="7">
                <MasterNode index="2" Position="0, 2, 0.15" Tangent="0, 0, 0" Up="0, 0, 1" />
+
            <Interpolation Periodic="1" type="CInterpolationBezier" />
            </Yarn>
+
            <YarnSection type="CYarnSectionConstant">
            <Yarn index="3" NumSlaveNodes="26" NumSectionPoints="20" NeedsBuilding="7">
+
                <SectionList index="0" type="CSectionEllipse" NeedsMeshing="1" Width="0.8" Height="0.2" />
                <Interpolation Periodic="1" type="CInterpolationBezier" />
+
            </YarnSection>
                <YarnSection type="CYarnSectionConstant">
+
            <Repeat value="2, 0, 0" />
                    <SectionList index="0" type="CSectionEllipse" NeedsMeshing="1" Width="0.8" Height="0.1" />
+
            <Repeat value="0, 2, 0" />
                </YarnSection>
+
            <MasterNode index="0" Position="0, 0, 0.3" Tangent="0, 0, 0" Up="0, 0, 1" />
                <Repeat value="2, 0, 0" />
+
            <MasterNode index="1" Position="0, 1, 0.1" Tangent="0, 0, 0" Up="0, 0, 1" />
                <Repeat value="0, 2, 0" />
+
            <MasterNode index="2" Position="0, 2, 0.3" Tangent="0, 0, 0" Up="0, 0, 1" />
                <MasterNode index="0" Position="1, 0, 0.05" Tangent="0, 0, 0" Up="0, 0, 1" />
+
        </Yarn>
                <MasterNode index="1" Position="1, 1, 0.15" Tangent="0, 0, 0" Up="0, 0, 1" />
+
        <Yarn index="3" NumSlaveNodes="25" NumSectionPoints="20" NeedsBuilding="7">
                <MasterNode index="2" Position="1, 2, 0.05" Tangent="0, 0, 0" Up="0, 0, 1" />
+
            <Interpolation Periodic="1" type="CInterpolationBezier" />
            </Yarn>
+
            <YarnSection type="CYarnSectionConstant">
            <PatternCell x="0" y="0">
+
                <SectionList index="0" type="CSectionEllipse" NeedsMeshing="1" Width="0.8" Height="0.2" />
                <PatternElement value="1" />
+
            </YarnSection>
                <PatternElement value="0" />
+
            <Repeat value="2, 0, 0" />
            </PatternCell>
+
            <Repeat value="0, 2, 0" />
            <PatternCell x="1" y="0">
+
            <MasterNode index="0" Position="1, 0, 0.1" Tangent="0, 0, 0" Up="0, 0, 1" />
                <PatternElement value="0" />
+
            <MasterNode index="1" Position="1, 1, 0.3" Tangent="0, 0, 0" Up="0, 0, 1" />
                <PatternElement value="1" />
+
            <MasterNode index="2" Position="1, 2, 0.1" Tangent="0, 0, 0" Up="0, 0, 1" />
            </PatternCell>
+
        </Yarn>
            <PatternCell x="0" y="1">
+
        <PatternCell x="0" y="0">
                <PatternElement value="0" />
+
            <PatternElement value="1" />
                <PatternElement value="1" />
+
            <PatternElement value="0" />
            </PatternCell>
+
        </PatternCell>
            <PatternCell x="1" y="1">
+
        <PatternCell x="1" y="0">
                <PatternElement value="1" />
+
            <PatternElement value="0" />
                <PatternElement value="0" />
+
            <PatternElement value="1" />
            </PatternCell>
+
        </PatternCell>
            <XYarnData index="0" Width="0.8" Height="0.1" Spacing="1" />
+
        <PatternCell x="0" y="1">
            <XYarnData index="1" Width="0.8" Height="0.1" Spacing="1" />
+
            <PatternElement value="0" />
            <YYarnData index="0" Width="0.8" Height="0.1" Spacing="1" />
+
            <PatternElement value="1" />
            <YYarnData index="1" Width="0.8" Height="0.1" Spacing="1" />
+
        </PatternCell>
            <XYarns index="0">
+
        <PatternCell x="1" y="1">
                <XYarn yarnindex="0" />
+
            <PatternElement value="1" />
            </XYarns>
+
            <PatternElement value="0" />
            <XYarns index="1">
+
        </PatternCell>
                <XYarn yarnindex="1" />
+
        <XYarnData index="0" Width="0.8" Height="0.2" Spacing="1" />
            </XYarns>
+
        <XYarnData index="1" Width="0.8" Height="0.2" Spacing="1" />
            <YYarns index="0">
+
        <YYarnData index="0" Width="0.8" Height="0.2" Spacing="1" />
                <YYarn yarnindex="2" />
+
        <YYarnData index="1" Width="0.8" Height="0.2" Spacing="1" />
            </YYarns>
+
        <XYarns index="0">
            <YYarns index="1">
+
            <XYarn yarnindex="0" />
                <YYarn yarnindex="3" />
+
        </XYarns>
            </YYarns>
+
        <XYarns index="1">
        </Textile>
+
            <XYarn yarnindex="1" />
        <Domain name="Planes(N:6)" type="CDomainPlanes">
+
        </XYarns>
            <Plane Normal="1, 0, 0" d="-0.5" />
+
        <YYarns index="0">
            <Plane Normal="-1, 0, 0" d="-1.5" />
+
            <YYarn yarnindex="2" />
            <Plane Normal="0, 1, 0" d="-0.5" />
+
        </YYarns>
            <Plane Normal="0, -1, 0" d="-1.5" />
+
        <YYarns index="1">
            <Plane Normal="0, 0, 1" d="-0.01" />
+
            <YYarn yarnindex="3" />
            <Plane Normal="0, 0, -1" d="-0.21" />
+
        </YYarns>
        </Domain>
+
    </Textile>
    </TexGenModel>
+
</TexGenModel>
 +
 
 +
====Elements====
 +
 
 +
Elements have the following format: <NAME> ... </NAME>. Everything between the tags is part of the element. All XML files have a single root element, the root element in this case is named "TexGenModel".
 +
 
 +
====Attributes====
 +
 
 +
Elements can contain attributes which come after the name of the element. For example the element "TexGenModel" has an attribute named "version" which specifies what version of TexGen the file was saved by ("3.0.0" in this example). All variables that can be expressed as a single string are stored as attributes (i.e. All the integral data types and small structs like XYZ and XY). The attribute name usually corresponds to the variable name without the Hungarian notation.
 +
 
 +
====Child Elements====
 +
 
 +
Variables that cannot be expressed as a single string are stored as child elements. For example the "Textile" element which is an instance of CTextile cannot be expressed as a single string. Hence "Textile" is a child element of "TexGenModel". The element name usually corresponds to the variable name without the Hungarian notation.
 +
 
 +
====Collection Classes====
 +
 
 +
When a variable is a collection class (i.e. vector, list or map) a child element is created for each item in the collection. For example, CTextile contains a vector of yarns, for this model the number of yarns within the vector is 4. Thus the "Textile" element contains 4 child "Yarn" elements. Sometimes the index of the element is given as an "index" attribute. This value is provided only for human readability, when TexGen reads the file this number is ignored. The true index is obtained simply by the order in which the elements appear.
 +
 
 +
====Subclasses====
 +
 
 +
In some cases a variable may be a pointer to a base class. It may represent any of the subclasses of the base class. In these cases an additional attribute is added to the element which represents it. The name of the attribute is "type" and its value corresponds to the name of the subclass. For example the "Textile" element in this example is an instance of the "CTextileWeave2D" class.
 +
 
 +
====API====
 +
 
 +
Please refer to the [http://texgen.sourceforge.net/api/ API] for information on what the elements and attributes represent.

Latest revision as of 13:37, 26 November 2009

The file format for storing TexGen data has the extension TG3 which stands for TexGen v3. It is an XML file where each element usually corresponds to a class within TexGen core. When a TG3 file is saved, there is an option as to how much data is saved:

No matter which of the options is chosen TexGen is able to read the data and recreate the exact some model as was originally saved provided files are saved and loaded by the same version of TexGen. Results may vary when loading a file from a different version of TexGen depending on the output type. For example, if the class to represent a specific textile (e.g. CTextileWeave2D) is modified so that the geometry is created in a different way. Files saved with an old version with minimal output will have the new geometry whereas files saved with standard or full output will retain the old geometry.

Minimal

When minimal output is selected only the information within the Textile derived class is saved. For example, if a textile was created with the CTextileWeave2D class then only the weave pattern, fabric thickness, yarn heights, widths and spacings will be saved. From this the yarn path can be reconstructed. If the textile being saved is not a derived class then it will save as Standard instead.

Standard

When standard output is selected then the information about the yarns will be saved as well. This includes yarn master nodes, interpolation function, yarn section, repeats, etc...

Full

When full output is selected then everything that TexGen stores in memory is saved to file. This includes information such as the actual points lying on the surface of a yarn. These files tend to be very large and should not be used unless it is absolutely necessary.

Structure

The file follows the XML conventions and as such is human readable. Here is an example file saved with Standard output:

<?xml version="1.0" ?>
<TexGenModel version="3.0.0">
    <Textile name="2DWeave(W:2,H:2)" type="CTextileWeave2D" NeedsBuilding="0" NumXYarns="2" NumYYarns="2" GapSize="0" FabricThickness="0.4" Refine="0">
        <Domain type="CDomainPlanes">
            <Plane Normal="1, 0, 0" d="-0.5" />
            <Plane Normal="-1, 0, 0" d="-1.5" />
            <Plane Normal="0, 1, 0" d="-0.5" />
            <Plane Normal="0, -1, 0" d="-1.5" />
            <Plane Normal="0, 0, 1" d="-0.02" />
            <Plane Normal="0, 0, -1" d="-0.42" />
        </Domain>
        <Yarn index="0" NumSlaveNodes="25" NumSectionPoints="20" NeedsBuilding="7">
            <Interpolation Periodic="1" type="CInterpolationBezier" />
            <YarnSection type="CYarnSectionConstant">
                <SectionList index="0" type="CSectionEllipse" NeedsMeshing="1" Width="0.8" Height="0.2" />
            </YarnSection>
            <Repeat value="2, 0, 0" />
            <Repeat value="0, 2, 0" />
            <MasterNode index="0" Position="0, 0, 0.1" Tangent="0, 0, 0" Up="0, 0, 1" />
            <MasterNode index="1" Position="1, 0, 0.3" Tangent="0, 0, 0" Up="0, 0, 1" />
            <MasterNode index="2" Position="2, 0, 0.1" Tangent="0, 0, 0" Up="0, 0, 1" />
        </Yarn>
        <Yarn index="1" NumSlaveNodes="25" NumSectionPoints="20" NeedsBuilding="7">
            <Interpolation Periodic="1" type="CInterpolationBezier" />
            <YarnSection type="CYarnSectionConstant">
                <SectionList index="0" type="CSectionEllipse" NeedsMeshing="1" Width="0.8" Height="0.2" />
            </YarnSection>
            <Repeat value="2, 0, 0" />
            <Repeat value="0, 2, 0" />
            <MasterNode index="0" Position="0, 1, 0.3" Tangent="0, 0, 0" Up="0, 0, 1" />
            <MasterNode index="1" Position="1, 1, 0.1" Tangent="0, 0, 0" Up="0, 0, 1" />
            <MasterNode index="2" Position="2, 1, 0.3" Tangent="0, 0, 0" Up="0, 0, 1" />
        </Yarn>
        <Yarn index="2" NumSlaveNodes="25" NumSectionPoints="20" NeedsBuilding="7">
            <Interpolation Periodic="1" type="CInterpolationBezier" />
            <YarnSection type="CYarnSectionConstant">
                <SectionList index="0" type="CSectionEllipse" NeedsMeshing="1" Width="0.8" Height="0.2" />
            </YarnSection>
            <Repeat value="2, 0, 0" />
            <Repeat value="0, 2, 0" />
            <MasterNode index="0" Position="0, 0, 0.3" Tangent="0, 0, 0" Up="0, 0, 1" />
            <MasterNode index="1" Position="0, 1, 0.1" Tangent="0, 0, 0" Up="0, 0, 1" />
            <MasterNode index="2" Position="0, 2, 0.3" Tangent="0, 0, 0" Up="0, 0, 1" />
        </Yarn>
        <Yarn index="3" NumSlaveNodes="25" NumSectionPoints="20" NeedsBuilding="7">
            <Interpolation Periodic="1" type="CInterpolationBezier" />
            <YarnSection type="CYarnSectionConstant">
                <SectionList index="0" type="CSectionEllipse" NeedsMeshing="1" Width="0.8" Height="0.2" />
            </YarnSection>
            <Repeat value="2, 0, 0" />
            <Repeat value="0, 2, 0" />
            <MasterNode index="0" Position="1, 0, 0.1" Tangent="0, 0, 0" Up="0, 0, 1" />
            <MasterNode index="1" Position="1, 1, 0.3" Tangent="0, 0, 0" Up="0, 0, 1" />
            <MasterNode index="2" Position="1, 2, 0.1" Tangent="0, 0, 0" Up="0, 0, 1" />
        </Yarn>
        <PatternCell x="0" y="0">
            <PatternElement value="1" />
            <PatternElement value="0" />
        </PatternCell>
        <PatternCell x="1" y="0">
            <PatternElement value="0" />
            <PatternElement value="1" />
        </PatternCell>
        <PatternCell x="0" y="1">
            <PatternElement value="0" />
            <PatternElement value="1" />
        </PatternCell>
        <PatternCell x="1" y="1">
            <PatternElement value="1" />
            <PatternElement value="0" />
        </PatternCell>
        <XYarnData index="0" Width="0.8" Height="0.2" Spacing="1" />
        <XYarnData index="1" Width="0.8" Height="0.2" Spacing="1" />
        <YYarnData index="0" Width="0.8" Height="0.2" Spacing="1" />
        <YYarnData index="1" Width="0.8" Height="0.2" Spacing="1" />
        <XYarns index="0">
            <XYarn yarnindex="0" />
        </XYarns>
        <XYarns index="1">
            <XYarn yarnindex="1" />
        </XYarns>
        <YYarns index="0">
            <YYarn yarnindex="2" />
        </YYarns>
        <YYarns index="1">
            <YYarn yarnindex="3" />
        </YYarns>
    </Textile>
</TexGenModel>

Elements

Elements have the following format: <NAME> ... </NAME>. Everything between the tags is part of the element. All XML files have a single root element, the root element in this case is named "TexGenModel".

Attributes

Elements can contain attributes which come after the name of the element. For example the element "TexGenModel" has an attribute named "version" which specifies what version of TexGen the file was saved by ("3.0.0" in this example). All variables that can be expressed as a single string are stored as attributes (i.e. All the integral data types and small structs like XYZ and XY). The attribute name usually corresponds to the variable name without the Hungarian notation.

Child Elements

Variables that cannot be expressed as a single string are stored as child elements. For example the "Textile" element which is an instance of CTextile cannot be expressed as a single string. Hence "Textile" is a child element of "TexGenModel". The element name usually corresponds to the variable name without the Hungarian notation.

Collection Classes

When a variable is a collection class (i.e. vector, list or map) a child element is created for each item in the collection. For example, CTextile contains a vector of yarns, for this model the number of yarns within the vector is 4. Thus the "Textile" element contains 4 child "Yarn" elements. Sometimes the index of the element is given as an "index" attribute. This value is provided only for human readability, when TexGen reads the file this number is ignored. The true index is obtained simply by the order in which the elements appear.

Subclasses

In some cases a variable may be a pointer to a base class. It may represent any of the subclasses of the base class. In these cases an additional attribute is added to the element which represents it. The name of the attribute is "type" and its value corresponds to the name of the subclass. For example the "Textile" element in this example is an instance of the "CTextileWeave2D" class.

API

Please refer to the API for information on what the elements and attributes represent.