Exporting T-Splines

[rami]

Hello,

I just wanted to ask if we can export from the plugin the TMesh or the the control mesh. If yes could you please tell me how and what is the format.

Thank you,
Rami Santina

[TomFinnigan]

Here's some information about the tspline format (we typically use the extension .tsp). Most of this conversation is from an email I wrote earlier, which assumes that the user is familiar with the OBJ file format. Our file format has several similarities with OBJ, although it also has significant changes, in order to maintain indices through load/save and handle T-Junctions and knot intervals.

You can load and save .tsp files via the command tsData. I think it's got help built into it, and I believe that it only works on the registered version of the plugin (although there is academic pricing if you're interested). You can also see the format if you save to a maya ascii file (which is also limited to the registered version).

We version our file format, so the first thing is a header. The current version of the format is 1.2. Earlier versions were more like obj, although changes have been made, as noted above.

I guess first, I should explain the format of our mesh. All of the components are single-indexed.
A vertex contains a face index (an index to one of the faces around the vertex) and a valence.
An edge contains two vertex indices, two face indices, and an interval index.
An interval contains a single double, the knot interval.
Faces are our heavy component. A face contains a list of edges, vertex flags, and UVs. The UVs are optional.

The ordering of the edges and flags is fairly straightforward. We use a CCW winding, and the vertex leads the edge. For example, if you have a square, edge 0 is on the left, vertex 0 is bottom-left corner. Edge 1 is on the bottom, vertex1 is bottom-right corner, etc.

The face also has a set of flags, indicating whether it holds geometry, beziers, or just knot information. If your shapes are all completely periodic, you don't need to worry about the face flags. (This was written to someone doing completely periodic shapes. I'll go back and edit the information about the face flags later).

Additionally, to maintain constant indices, we allow gaps in our indices. That is, if you've deleted vertex 30, vertex 31 is still vertex 31 after saving and reloading.

Here's information about the formatting.

vertices
=====
The tag is v. A v without any other arguments on the line is a deleted vertex.
The other arguments are the parent face index (-1 for invalid) and the valence.
v [ <face index> <valence> ]

edges
====
The tag is e. As with all of the components, just an 'e' on a line means it's a deleted edge, just in there to preserve the indices. The other arguments are vertex 0 and vertex 1, face 0, face 1. If the vertices or faces are invalid (as in the case near the edge of a mesh) then they will be -1. The edge is fairly unconstrained, in that there's no necessary relationship between the positions of the indices of the vertices and faces.
e [ <vertex0 index> <vertex1 index> <face0 index> <face1 index> ]

texture coordinates
============
The tag is vt. The indices used are just for the file, so we don't have blank vt lines. The format is simply
vt <u value> <v value>

faces
====
The tag is f. They can be deleted, and UVs are optional. The flag is whether the vertex is a T-Junction on that face. For example, a simple T-Junction is a corner for two faces, and a T-Junction for the third face.
Here's some amazing ascii art:

Code: Select all

Say you have a mesh with the following local topology:
.-----.
|     |
.--.--.
|  |  |
.--.--.

Here it is, labelled:
.-----.
|  f1 |
.--V--.
|f2|f3|
.--.--.

Vertex V is a T-Junction on f1, but it is not a T-Junction on f2 or f3.


f [<edge index0>/<is vertex0 T-Junction on face>[/<UV index0>]
<edge index1>/<is vertex1 T-Junction on face>[/<UV index1>] ... until vertex n.

That should be the basics of the file format. Of course, we reserve the right to change the format, although we'll try to maintain backwards compatibility (for reading files, at least).

Tom Finnigan

[Adam Helps]

The file format has already changed from the one listed here, actually.

To write a reader that will be compatible with our file format into the future, you need to IGNORE lines that start with a string that you don't recognize. For example, we have an "fs" tag for marking face set partitions on the T-Spline. A typical line would look something like this:

fs 1/10 1/11 1/13 1/14 2/58 2/59

All that you need to know in your reader is that this line starts with "fs," which is a tag you do not recognize. You may safely ignore this line, because it gives useless information.

[TomFinnigan]

I was looking at this file format description, and thought I'd update it to the latest version of the tsp file format (1.2).

First, if you're just looking to work with the T-Splines shape in another program, we have a command tsDumpBeziers that will let you extract the individual Beziers, either as geometry or in a factored form suitable for some kinds of reverse engineering research. Please see the other post on the topic.

We also have a c++ library that makes working with T-Splines easy, and which we used to create the T-Splines plugin. The library is available for license, and includes a diagnostic viewer and validity checker/repair.

----

I'll go ahead and document the format from the function that writes it:

Output stream precision is set to 20

Header reports tsp format version 1.2 (#TS0102)

- subdiv <subdivision level>
Number of local subdivisions to perform before extracting a smooth surface, analogous to the tsSetSubdivision level rhino command. Optional.

- extractor <extractor type>
In the 1.x codebase, we had two different surface computation algorithms. For the rhino plugin, this will always be 1, for the Maya plugin this will be 0. Also optional, it will default to the correct value.

- v
This is a vertex that has been deleted, and is included to maintain index consistency

- v <xw> <yw> <zw> <w> <parent face> <valence>
This is a vertex similar to the OBJ file format. The parent face is one of the adjacent faces, and gives orientation to the vertex. -1 is an invalid face. The valence is simply the number of edges (or equivalently, faces) connected to the vertex.

- kl <knot interval 0> <knot interval 1> <knot interval 2> ... <knot interval n>
This is the knot interval list. Each edge in a T-Spline has a knot interval. For 1.x we used a central list, and indexed into that list. The kl tag lets you dump this list in a single line. By default we output 5 per line.

- e
A deleted edge.

- e <v0> <v1> <f0> <f1> <knot interval index>
The two vertices, the two faces, and the index into the knot list. If the edge is on the border of the mesh, one of its faces may be -1. Very high edge

- vt <u> <v>
UV location.

- f
A deleted face.

- f <face flags> <edge index0>/<vertex0 is T>[/<texture index0>] <edge index1>/<vertex1 is T>[/<texture index1>] ...
The face has several flags that are bitwise-or'd together into an integer. The flags are:
Visited = 1. This is inconsequential.
HideBezierFace = 2. This is set for faces with no shown beziers.
IsVirtual = 4. This is set for faces which only have knot interval information, but an incomplete set of vertices.
For example, in a simple bicubic bezier represented as a t-spline, it is a grid of 5x5 faces. The central face is normal, and has flags=0. The next ring has vertices, but no beziers, and have flags=2. The next ring has incomplete vertex information, and is virtual. It has flags=6.
The edge indices should be valid, and the vertex is T is as explained in the earlier forum post. Texture indices are still valid in the format. They are output and used by version 1.5 of the rhino plugin, but are not output by version 2 of the rhino plugin.

[Adam Helps]

One other addendum on the TSP file format -- if you see a line prefix that you do not recognize, you are required to silently ignore it. This allows us to maintain forward and backward compatibility.

If your file reader cannot handle unrecognized lines by ignoring them, you will not be able to read many of the TSP files we output. For our TSP code, I believe the main type of extra data is sets of vertices/faces/edges.

It's also permissible to add your own tags for application-specific data, but you should talk to us before doing that to avoid naming collisions.

[Chenna]

I have some queries over this FACE/EDGE/VERTEX format.
I think local knot vectors for the existing control points are evaluated based on the edges(hence knot interval) connected to the particular control point.
Can you please explain
1.) How the local knot vector, in direction perpendicular to refinement direction, are computed for a newly inserted control point as per Rule #1? Do you create global knot vectors for this purpose ?
2.) How the validity of the T-Mesh w.r.t different violations is checked ?

[Adam Helps]

This thread is about the TSP file format, which we don't support anymore...

With regard to face/edge/vert file formats, I suggested using a more NURBS-like representation in another thread. Take a look at that and see if it helps with your questions, please.

[afullo]

Hello,

I just wanted to ask if we can export from the plugin the TMesh or the the control mesh. If yes could you please tell me how and what is the format.

Thank you,
Rami Santina

This thread is about the TSP file format, which we don't support anymore...

If, as posted earlier, TSP is now deprecated, is this possibile to obtain the same result (exportation of TMesh and/or control mesh) with the new formats (I've seen TSM and TSS in the list of choices, but I don't know whether they are the only two suitable)?
Or, in the case, do I have to install an older version of the plugin which still supports TSP?

Thanks in advance.

[Nicholas North]

Hi afullo,

TSM files replaced TSP files. A TSS file is just a container for multiple pieces of data (usually in binary form, like a compressed TSM file). So if you want to export a T-Spline, the easiest way is to use TSM.

Since we've never described the TSM file format in detail before, we've decided to post a description of the format that we made internally to document it. Here it is:

TSM format.zip

ZIP file containing a text document explaining the TSM file format

(7.68 KiB) Downloaded 165 times

I zipped it up because our forum doesn't like plain-text attachments and it's too long to just post the contents directly.

Hope that helps.
-- Nick

[afullo]

Good . Just two more questions:

1. What does them mean?

Code: Select all

cap-type 1
star-smoothness 0

2. Are there "grips" control points? They are specified in terms of Cartesian coordinates and weight, and as far as I know they are the only part of a T-spline definition which use them...

Thanks again.

[Nicholas North]

1. cap-type and star-smoothness control how we approximate the surface around star points when converting to NURBS. The limit surface of a T-NURCC in the one-neighborhood of a star point is defined by repeated refinement. This means we have to approximate the limit surface near a star point in order to be NURBS-compatible. We refer to this approximation as "capping" because we're capping the "hole" in the surface that is only defined by infinite subdivision.

cap-type controls the continuity of the patches generated in the capping region. You should really only see values of 0 and 1 here, which means G0 or G1 caps, respectively. In Rhino, the user can change the cap-type by working in "compatible" (G1 caps, constantly provides NURBS to Rhino), "fast" (G1 caps, only provides a tessellated T-Spline to Rhino), and "fastest" (G0 caps, only tessellated).

star-smoothness controls how many local subdivisions are performed before capping. In early version of the plug-in we would routinely set star-smoothness to about 2. But our capping improved quite a bit somewhere around v2, so now star-smoothness is set to 0 by default.

These options are accessed through the tsOptions command.

2. Yes; grips store the geometric location of individual control points. There is also the concept of a vert. The difference is the same a geometric vs. topological. Grips are the geometry (that is, the physical location of something) while verts are the topology (how things are connected to each other).

A lot of the time there is a 1:1 relationship between a grip and a vert. However, we also support the concept of a compound grip: when a single vert (topological location) has multiple grips. This is our implementation's way of handling zero knot intervals (multiple knots in NURBS-speak). Separating verts and grips allows us to handle this one-to-many (vert to grips) relationship more cleanly.

Note that TSP files (and versions of the plug-in before TSM files were introduced) didn't separate verts and grips conceptually. This concept is probably the biggest reason why we dropped the TSP format in favor of TSM.

-- Nick

[afullo]

Acknowledged, ty. I've completed my work.