Houdini 20.5 Nodes Geometry nodes

UV Flatten 3.0 geometry node

Creates flattened pieces in texture space from 3D geometry.

On this page
Since 17.0

Overview

To apply a texture image to a 3D model, you must first create flattened version of the 3D geometry in texture space, so the computer knows how to map pixels in the flat image onto points on the 3D surface. This flattened representation of the model is stored as UV coordinates in an attribute (usually uv) on each vertex of the geometry.

This node works in two steps. It takes individual texture pieces (defined by seams that cut the model’s geometry up into smaller pieces that are easier to work with) and flattens them into 2D texture space, trying to equalize polygon size.

Note

This node packs the UV pieces using an algorithm optimized for interactivity. To get more options and the most efficient packing, follow this node with a UV Layout node.

This node lets you add constraints for the flattening algorithm. Constraints force the layout algorithm to satisfy certain conditions, giving you extra control over the final UV layout.

You can use this node interactively, using the tools in the node’s state to specify constraints, or you can turn off Manual layout and use the node procedurally.

Note

This node uses Intel’s Math Kernel Library when run on x86 processors. You can use an environment variable to tune the library for speed or for producing identical results from run to run.

Workflow

To...Do this

Set up the viewer to show UVs

By default, the Houdini viewer only shows one view, the Perspective view (“Persp”). You can switch to a multi-viewport layout and then switch one of the viewports to show the current network’s geometry in UV space.

  • To set how the viewer is split, click the layout menu icon at the far right end of the viewer tool, then select a layout such as “Four views” or “Two views side-by-side”.

  • To switch a viewport to show UV space, click the View menu (the left menu in the top right corner of a viewport) and choose Set view ▸ UV Viewport, or hover the mouse over the viewport and press Space + 5.

Use UV Flatten to lay out a model’s texture space

  1. You should set up the viewer to show a UV view.

  2. Select the geometry you want to flatten in texture space.

  3. On the Texture shelf tab, click the UV Flatten tool.

  4. Use the controls in the operation toolbar (across the top of the viewer) or in the parameter editor to change how the node works.

Note most geometry will flatten into self-overlapping pieces at first. For example, if you apply UV Flatten to a torus, the node will simply project the top and bottom of the torus down on top of each other in the UV plane. You need to cut UV seams to allow the node to “unwrap” separate 3D pieces into non-overlapping flat pieces.

Add constraints

When the node’s state is active in the viewer, you can use the tool icons in the operation toolbar at the top of the viewer to switch between tools allowing you add constraints by clicking the viewer.

(You can also switch tools using the context menu in the viewer.)

See quick selection for how to switch some tools between working immediately when you click, or waiting for you to make a selection and press Enter.

Remove a constraint

  • To remove a seam, use the Sew tool.

  • To remove a /nodes/sop/pin.html#pins, click the pin to select it, then press ⌦ Del.

  • To remove an alignment or straighten constraint, click one of the aligned edges to select it, then press ⌦ Del.

  • To remove a rectangular constraint, click a rectangular-ized region to select it, then press ⌦ Del.

Show the UV Flatten interface back in the viewer again

If you ever press ⎋ Esc to switch to the View tool, or switch to a different node, the viewer will switch to show the interface for the new tool.

To get the UV Flatten interface back, select the UV Flatten node in the network editor, then click the Handles tool or press Enter in the viewer.

Specify the area to pack into

When the UV Flatten tool is active, it shows a box handle in the UV view around the 0,0 to 1,1 area. The node packs flattened pieces within this are. You can drag the corners or sides of the box to change the size/shape of the packing area. You can also use the Center and Size parameters to set the box’s coordinates exactly.

This is useful if you need to avoid existing UV islands already in the UV attribute, or if you want to pack the pieces into a UV area other than 0,0 to 1,1.

Note

If you've pinned any pieces, they won’t move/resize when you change the packing area.

Quick selection

  • When quick selection is on (the default), certain tools react immediately to clicks:

    • In the Cut tool, clicking an edge makes the edge a seam.

    • In the Sew tool, clicking a seam edge removes the seam.

    • In the Rectify tool, the tool highlights quad grid regions as you move the mouse pointer over them. Clicking in a quad grid region will select the entire region (you still need to press Enter to apply the constraint).

  • When quick selection is off, you must select points/edges/faces, then press Enter in all tools.

To...Do this

Turn Quick Selection on or off

In the viewer, right-click and choose Quick Selection.

Understanding manual layout

There are two ways of using UV Flatten: interactively, and procedurally. You can switch between them, but you should understand the difference in how the node works.

  • When you use the node interactively (the default), the node will apply some constraints (Layout constraints) such as cutting seams before packing, then use the shapes influenced by those constraints to pack the pieces. Then, you can create more constraints interactively (for example, cutting more seams or pinning UVs). These constraints (Flattening constraints) are applied on top of the packed layout.

    This is because re-packing after each small change could radically alter the layout, making it extremely hard to work interactively with the pieces jumping around. By applying interactive changes post-packing, pieces won’t move as you work on them.

    When you want to “commit” your interactive changes and re-pack for the most efficient layout with the new constraints, click the Repack button in the operation toolbar at the top of the viewer. When you click Repack, the node copies the post-packing “flattening” constraints you added interactively into the pre-packing “layout” constraints parameters. The node then repacks the pieces taking those constraints into account.

    You can work in a cycle like this, making interactive changes, repacking to see their effect on the layout, and then making more interactive changes if necessary.

  • You might not care about flattening interactively and want the node to work procedurally. For example, you might calculate the seams somehow using a script. Or you might have existing islands and just want to use this node for layout and/or relaxing the UVs. In this case you want changes to the parameters to be immediately visible in the output, without having to click Repack.

    To set the node to work procedurally, turn off the Enable manual layout parameter (under the Layout constraints).

    When Enable manual layout is on, the “Flattening” constraints are the only constraints, and they are applied before packing. There are no post-packing constraints. Any values in the “Layout” constraints parameters are ignored.

    In this mode, any changes you make to the “Flattening” constraints immediately changes the node’s output.

Seams

Seams specify where the algorithm will cut the geometry into pieces. If a model has no seams at all, this node will fall back to simply projecting the geometry down onto the UV plane. Unless a model is extremely simple, this will produce bad distortion and overlap of UV pieces.

This node will not automatically add seams. You can precede this node with a UV Autoseam node, and/or manually cut seams using the Cut tool. You will usually need to cut geometry into at least a few pieces to prevent them from overlapping when flattened.

To...Do this

Cut seams interactively in the UV Flatten tool

  1. Click the Cut icon in the operation toolbar (across the top of the viewer).

  2. Whether secure selection is on or off changes how the cut tool works. See secure selection below.

Join seams back together

  1. Click the Join icon in the operation toolbar (across the top of the viewer).

  2. Whether secure selection is on or off changes how the join tool works. See secure selection below.

This tool “un-cuts” edges that were seams (edges in the seams group or edges that you cut interactively). You only need to click/select one side of the “split” in the UV view and both sides will join together. You can’t use this tool to join edges that are boundaries in the 3D model.

When you start joining edges, it may get hard to see/click individual edges as the flattened pieces starts to overlap itself. You may find it easier to click/select edges in the 3D Perspective view than the UV view.

Repack the pieces taking into account new seams

Click the Repack button in the operation toolbar (across the top of the viewer).

Tips

  • You can click edges in the UV view or the 3D views.

  • The node has two parameters for holding seams: “Layout” Seams and “Flattening” Seams. This is to accommodate interactive seam cutting. When you interactively cut seams, the new seams are added to the “Flattening” seams parameter. These seams affect flattening (the shape of the piece will change as you cut), but not layout (the node will not re-pack all the pieces in different positions as you cut).

    When you click Repack, the node will copy from “Flattening” Seams to “Layout” Seams (so they will affect the layout), and clear Post-packing.

    See understanding manual layout below for more information.

  • Island boundary edges are bright green in the UV view. “New” seams (in the Post-packing parameter) have a thicker line.

Pinning vertices

A pin keeps a single point on a piece at the same UV coordinates. When the node recomputes flattening and layout, the vertex will stay in place. However, dragging a pin will move the pinned point, and all other unconstrained points will move/rotate to accommodate the new pin position. (You can use this to rotate an island, by pinning the rotation pivot, then adding a second pin and dragging it around the first.)

To...Do this

Pin vertices in place

  1. Click the Pin icon in the operation toolbar (across the top of the viewer).

  2. Select one or more vertices in the UV view to turn into pins, then press Enter.

Move a pin

  1. Click the Pin icon in the operation toolbar (across the top of the viewer).

  2. Click an existing pin.

    A move handle appears on the pin.

  3. Drag the handle to move the pin.

  • You can move an island by putting a pin in the island and dragging the pin around in texture space.

  • You can rotate an island by putting two pins in the island and dragging one pin around the other.

Delete a pin

  1. Click the Pin icon in the operation toolbar (across the top of the viewer).

  2. Click an existing pin.

  3. Press Delete.

Tip

You must have the Pin mode selected to work with pins. For example, if you are in the Cut mode and click a pin, the tool will cut the edge under the pin.

Aligning and straightening

You can tell the node that you want certain groups of edges to be straight, or to be aligned with the UV grid. The node will take these hints into account when it re-flattens the texture pieces.

Tip

Edges may not become completely straight or axis-aligned if those hints conflict with other constraints, such as pins. Removing the other constraint(s) will cause the node to re-flatten with better straightening/alignment.

To...Do this

Straighten edges (ABF only)

  1. Click the Straighten icon in the operation toolbar (across the top of the viewer). This mode is only available when the Flattening method is “Angle-based (ABF)”.

  2. Select some contiguous edges, then press Enter.

    The node will remember that you want these edges to be straight when it re-flattens the texture piece.

Align vertices to the U or V axis

  1. Click the Align icon in the operation toolbar (across the top of the viewer).

  2. Select the vertices you want to align with each other, then press Enter.

    The tool uses a heuristic to choose to align to U or V based on which axes the points are closer to. If you want to change the alignment axis, expand the Axis aligned vertex groups heading in the parameter editor, find the alignment constraint you just created (at the end of the list of constraints), and change the Align parallel to parameter for that constraint.

Repack the pieces taking into account new straighten/align constraints

Click the Repack button in the operation toolbar (across the top of the viewer).

Making quads rectangular

For regions containing a regular grid of quadrilateral polygons, you can constrain those polygons to lay out as a rectangular grid aligned along the UV axes. This reduces distortion and can make the layout clearer.

To...Do this

  1. Click the Rectify icon in the operation toolbar (across the top of the viewer).

  2. If Quick Selection is on, this tool highlights quad grid regions as you move the mouse pointer over them, and selects the entire region with one click. If Quick Selection is off, you must select all the primitives you want to align and then press Enter.

Visualization

When the tool’s state is active in the viewer, it overlays a pattern on the model allowing you to visualize the UVs. This can make it obvious where you have distortion or overlap.

To...Do this

Turn the overlay off

In the viewer, right-click and choose Visualize texture ▸ Off.

Turn off display of materials/textures so you can see the overlay better

In the display toolbar on the right side of the menu, turn off the Display Materials on Objects button.

Change the overlay pattern

In the viewer, right-click and choose Visualize texture, then choose a pattern.

Turn on Display orientation glyph in this menu to add an “L” shape to the pattern to help you tell when the texture is right-side-up.

Change the overlay scale

In the viewer, scroll up or down to change the scale of the overlay pattern.

Parameters

Group

The polygonal faces to flatten in texture space. If this is empty, the node works on all incoming polygons. You can enter the name of a group here or specify polygons by number. Click the Reselect button next to this field to select different polygons in the viewer.

UV Attribute

The name of the attribute to store the UV coordinates (uv by default). You can enter a different name if you want to have multiple sets of UVs on the same geometry.

Flattening Method

How to flatten 3D geometry into 2D texture space. The node has two different methods that allow different hints (constraints) and have different efficiencies. Both methods are designed to minimize angular distortion, meaning that angles in the texture image should appear correct when projected onto the textured 3D surface. The methods differ mainly in how to handle area distortion, that is keeping polygons roughly the same size in texture space.

Spectral (SCP)

The default. Faster, more robust, slightly lower quality than Angle Based.

Angle Based (ABF)

Slower, may not always solve, higher quality (less area distortion).

Existing UVs

What to do with existing texture pieces if there are already texture coordinates in the UV attribute.

Preserve Seams

Any existing seams in the incoming geometry are added to contents of the Seams parameter.

Preserve Layout

Preserves the positions of any existing UV islands, and tries to lay out new islands around them.

Preserve Island Boundary Shapes (SCP only)

Preserves the shape of any existing UV islands (allowing them to rotate or scale), and re-flattens their interior UVs. You can turn on this option and Preserve layout if you want to preserve existing islands in-place but relax their UVs.

Flattening constraints

Seams

When Enable manual layout is off, these are the “interactive” post-packing seams. Any edges in this parameter that are not in the “Layout” seams parameter are cut, and any edges in the “Layout” seams parameter that are not in this parameter will be joined. When Enable manual layout is on, these are the only seam constraints, and the “Layout” Seams parameter is ignored.

See understanding manual layout above for more information.

Rectify group

A set of edges defining a rectangular grid of quadrilateral polygon. The tool lists all edges in the selected region, but if you are filling this field in procedurally, it’s sufficient to fill in only the horizontal vertex edges. This is a list of vertex edges.

Vertex pins

Enable pins

A “master switch” to enable or disable all pins.

This section contains a multiparameter where each item corresponds to a pin. You can edit the pins by changing the parameters but it is usually easier to change them interactively. See pinning vertices above.

Primitive/Vertex

The primitive number of the polygon containing the pinned vertex and the sequential index of the pinned vertex in that polygon.

UV

The coordinates to pin the vertex to.

Reference UV

The UV coordinates of the next vertex in the same polygon. It is ignored unless the pin is the only pin in its respective island. Mainly used in interactive state.

Axis-aligned vertex groups

Enable Axis Alignment

A “master switch” to enable or disable all alignment constraints.

This section contains a multiparameter where each item corresponds to an alignment constraint. You can delete individual constraints here. See aligning edges above.

Group

The vertices to line up. Note that it is enough include only one of possibly several vertices in the island wired to the same point.

Align Parallel To

Axis along which to line up.

Straightened Loops (ABF only)

Enable Loop Straightening

A “master switch” to enable or disable all straightening constraints.

This section contains a multiparameter where each item corresponds to a straightening constraint. You can delete individual constraints here. See straightening edges above.

Group

A group of vertices that describe a sequence of edges to be forced into a straight line. This is a list of vertex edges.

Layout constraints

Enable manual layout

Switches the node to work non-interactively. The Flattening constraints will be applied before packing, and the Layout constraints will be ignored. This allows you to use the node procedurally, where changes to the parameters immediately change the node’s output, without having to click Repack.

See understanding manual layout above for more information.

Seams

When Enable manual layout is off, these are the “base” pre-packing seams. When Enable manual layout is on, the “Flattening” seams are the only seam constraints, and this parameter is ignored.

See understanding manual layout above for more information.

Output groups

Seams

Turn the checkbox next to this parameter on to create an edge group in the output containing the seam edges.

Constrained Islands

Turn the checkbox next to this parameter on to create a primitive group in the output containing the polygons in all islands that have a pin, axis-alignment, or straighten constraint.

Packing area

Controls the area of texture space within which the node will try to pack the texture pieces. You can use these parameters to position the area exactly, or drag the corners or sides of the box handle in the UV view when this node is active.

Center

The center of the packing area, as UV coordinates.

Size

The width and height of the packing area, in UV units.

About vertex edge groups

The rectify group and straightened group fields contain list of vertex edges. Each edge is represented by a vertex number. Each vertex number implies a vertex edge from that vertex to the next vertex clockwise.

These fields have to use vertices instead of primitive edges because primitive edges are shared between the polygons on either side. If that particular edge was a seam, it wouldn’t be clear which side was supposed to be aligned.

See also

Geometry nodes