Transformation roadmap

[webdevred]

What is transformation?

Transformation is everything in the codebase that aint Formatting and Parsing, for example sorting vertices and moving them to correct tree type. This code is as of writing this marked/experimental unstable in the master branch and will probably be for a while since I have many breaking changes planned and there are no unit tests since a upcoming refactoring could cause me to remove some of the unit tests. I plan to add unit tests whenever the codebase stabilizes.

How does transformation work?

You’ve got a raw data structure (Node) that describes vertices and beams (kind of like a messy blueprint). The goal is to clean it up, reorganize the vertices, and rename them consistently.

Here’s how the modules work together:

SupportVertex

1. Scans the "beams" section.
2. Counts how many connections each vertex has.
3. Produces a map of vertex → connection count.
4. This helps later to spot support vertices (the ones holding stuff up).

VertexExtraction

1. Digs into the "nodes" section.
2. Reads raw vertices, pulls out metadata and comments.
3. Groups them into a VertexForest (trees like Left, Middle, Right, Support).
4. Handles global vs. local metadata so values aren’t duplicated.

Transformation

1. Takes the VertexForest + the connection map from SupportVertex
2. Decides where each vertex belongs (Left/Middle/Right/Support).
3. Sorts them in order, groups them by prefix, and renames them with consistent IDs (l1, m2, r3…).
4. Rewrites the whole Node tree with the updated vertices.
5. Updates all other references to these vertices so names stay in sync.

End result

The input data becomes a neat structure:

• Vertices are in the right groups.
• Support vertices are identified and placed correctly.
• Metadata is cleanly separated into global vs. local.
• Names are consistent and collisions are avoided.

Basically, the system turns raw vertex + beam data into a well-organized, fully updated node tree ready for further use.

Previous changes

1. Transformation reimplemenation: before errors were handled less safely and meta groups interrupting vertex groups was not supported Reimplement transformation, handle Meta Nodes interrupting vertex grouping #2
2. Transformation refactoring: split Transformation into different files and added improved how comments and metadata is handled when moving vertices Transformation.hs refactoring #41
3. Sorting threshold: support for configuring a threshold which decides when two Y values are too close and compare Z values instead feat(transformation): z-sorting threshold via YAML config #38
4. Prefix replacement: added a argument which can provide replacement values for the vertex prefixes Prefix replacement from cli arguments #50
5. Support vertex detextion: implemented detection of support vertices and automatically moving them to their own tree Support vertex detection #52
6. Associate comments without newline before with prior node Associate comments without newline before with prior node #56

Remaining problems as of September 2025

Better support vertex detection:
Currently this is how vertices are detected:

  let annVertexCount = round $ supThr * fromIntegral (length annnotatedVertices) / 100
      isSupportVertex' v = any (>= annVertexCount) $ M.lookup (vName . aVertex $ v) conns
      (supportVertices, nonSupportVertices) = partition isSupportVertex' annnotatedVertices

So basically it works like this:

1. Calculate how many vertices there are
2. Multiply by supThr, by default 97
3. Dvivide by 100 and save the value as annVertexCount
4. Determine if the amount of connections for the vertex in the whole mesh are higher than annVertexCount

Ideally it should instead work like something like this:

1. Count direct connections: For each vertex in the VertexTree, count how many direct connections (edges) it has to other vertices.
2. Compute the threshold: Determine a threshold based on a percentage of the total number of vertices in the VertexTree. Only vertices whose number of direct connections exceeds this threshold are considered potential support vertices.
3. Identify potential support vertices: A vertex with many direct connections, especially when the vertices it connects to themselves have relatively few connections back. likely serves as a support vertex.

In other words, vertices that act as hubs, with a high proportion of connections relative to the size of the VertexTree, are more likely to be support vertices.

Better comment handling:

      [    "id",   "posX",   "posY",   "posZ"],
      {"frictionCoef" : 0.7},
      {"nodeMaterial" : "|NM_METAL"},

      // Left side
      {"collision" : true},
      {"group" : "cot_fender_l"},
      {"nodeWeight" : 0.65},
      {"selfCollision" : true},
      [  "bfl0",    0.948,   -1.435,    0.730],
      [  "bfl1",    0.756,   -1.413,    0.843],
      [  "bfl2",    0.963,   -1.024,    0.112],
      [  "bfl3",    0.964,   -1.072,    0.507],
      [  "bfl4",    0.778,   -1.008,    0.873],
      [  "bfl5",    0.987,   -0.743,    0.109],
      [  "bfl6",    0.987,   -0.744,    0.494],
      [  "bfl7",    0.812,   -0.759,    0.896],

      // prefix group vfl
      [  "vfl0",    0.739,   -1.845,    0.716],
      [  "vfl1",    0.959,   -1.762,    0.576],
      [  "vfl2",    0.855,   -1.788,    0.707],

Currently, when multiple VertexTrees are combined, such as when there are multiple vertex prefixes for a single VertexTree type, a comment is added to indicate the combination. However, comments that appear at the top of some of the individual VertexTrees may be lost during this process and not preserved in the final combined VertexTree. This will be fixed.

[webdevred]

Refined plan for support node detection

After some internal discussions, we revised the idea for support node detection. Here is the current plan.

Input

We have a data structure mapping each vertex group (VertexTreeType) to its list of vertices:

Map VertexTreeType [Vertex]

Each vertex may be connected via beams to other vertices, either inside the same group or outside the group.
The goal is to identify support nodes, vertices that act as structural anchors for their group.

Algorithm Steps

1. Compute vertex counts and connections per vertex tree

   • For each vertex tree (in this case it is just a (VertexTreeType, [Vertex]) pair):
     • Determine the total number of vertices in the tree.
     • For each vertex in all trees, count all beams that connect it to any vertex within this specific vertex tree resulting in something like Map Text Int for each vertexTree.

2. Select the most connected vertex

   • For each tree, identify the vertex with the highest number of connections to that tree.

3. Classify support nodes

   • If the number of connections of the most connected vertex is greater than 80% of the total number of vertices in that tree, classify it as a support node.

[webdevred]

Problems as of November 2025

Better comment handling:

I am still working on this, a draft is available in #89

Perform updates in whole folder after renaming nodes:

In JBeam, nodes define points in a vehicle’s structure, and beams connect them. If you rename nodes in one file, it’s crucial to update all references in other files because beams reference nodes by name and if the names don’t match, parts can break or behave incorrectly.

When I will get time, I will write a more detailed plan on how this will work. I am currently focusing on improving the formatter.

Updated diagram