Snap Tutorial

Use the File > Open menu to load share/documents/snap_test_1.k3d. You will see a torus primitive and a grid.

In the panel to the left of the viewport, click on "Node Properties" and change it to "Tool Properties".

In the viewport, click the Left Mouse Button on the torus to select it. The wireframe outlines of the torus will change from black to white when it's selected. (You might have to click twice, once to focus the viewport, once to select the torus).

Use the Edit > Tools > Snap Tool menu to select the snap tool. Note the properties that appear in the Tool Properties Panel, and the Snap Tool manipulators that appear at the center of the torus in the viewport.

Use the Snap Tool manipulators and drag the mouse in the viewport with the Left Mouse Button down to freely move the torus in the viewport. Note that the manipulators allow motion constrained to the three axes, the three planes, or the screen plane.

In the Tool Properties Panel, change "Target" to "Axes" (the grid). Use the manipulators to move the torus, and note that its position is now constrained to the grid intersections. This demos a source (the torus) with a single implicit snap source (its center point), snapping to a target (the grid) with a single implicit snap target (the grid points).

Use the File > Open menu to load share/documents/snap_test_2.k3d. You will see a torus, a large sphere, and the grid.

Switch the Node Properties Panel to Tool Properties again, select the torus, and pick the Snap Tool from the Edit > Tools menu.

Switch the Target to "Sphere" in the Tool Properties Panel. Drag the torus near the sphere, and see that it snaps to the sphere surface. Note that the orientation of the torus changes so that it lies "flat" on the sphere surface. This demonstrates snapping both position and orientation.

Drag the torus away from the sphere and note that the snap behavior has a limited "range". Change "Snap Distance" in the Tool Properties Panel to alter the range.

Disable "Snap Orientation" in the Tool Properties Panel and drag the torus near the sphere once again. Note that the torus snaps to the surface of the sphere without altering its orientation. This demonstrates that snap position and orientation can be independently controlled.

Change the "Target" to "Axes" and see that the torus snaps to the grid once again.

Use the File > Open menu to load share/documents/snap_test_3.k3d. You will see a torus and a disk. Switch the Node Properties Panel to Tool Properties, select the torus, and select Edit > Tools > Snap Tool once again The snap tool manipulators won't be centered on the torus this time, this is caused by a limitation of the current Snap Tool which is a heavly-modified version of K-3D's Move Tool. Once you begin moving the manipulators, the torus will follow them normally.

Pick "Target" "Snap Disk" in the Tool Properties Panel, and move the torus around the disk. You will see that it snaps to four positions around the edge of the disk. Although it isn't obvious, these four snap targets were added to the disk manually using a script, and saved to disk as part of the document. This demonstrates explicit snap targets, as these targets are not implicitly part of the disk primitive, they were added from the outside. The previous samples are all examples of implicit snap targets, which are coded into the primitives themselves.

In the Tool Properties Panel, change "Snap Target" to "-x", and see that the torus now snaps only to the left edge of the disk. This demonstrates explicit user control over the choice of snap target. The previous examples demo automatic choice of snap target (the snap tool picks whichever snap target is closest to the source).

Use the Scripting > Play menu to run the script share/scripts/snap_test_1.py. You will see two overlapping blocks in the viewport.

Select the smaller of the two blocks, switch to the Tool Properties panel, and select the Snap Tool. Set the "Target" to "Floor Instance" in the Tool Properties Panel.

Use the Snap Tool manipulators to move the smaller block up, down, and around the viewport. Note that the only place the smaller block snaps is with its bottom aligned with the top of the larger block. This is an example of snap groups, where the snap source at the bottom of the smaller block will only snap to snap sources that are in the same group.

Turn off "Match Groups" in the Tool Properties Panel, and move the smaller block around again. Note that there are six snap targets on the larger block where the smaller block will snap.

Open the file share/scripts/snap_test_1.py in a text editor to see how the explicit snap sources and snap targets were added to the two blocks.