KeenTools PinTool Guide



PinTool was created to help VFX artists with placing of 3D objects into 2D still images as quick and simple as possible. After placing an object into the scene an artist is able to animate it adjusting the object’s position in sequential frames doing kind of a manual tracking. Finally, when the object is placed across all the frames of a footage an artist can use the geometry of the object to work on various compositing tasks.


To start working with PinTool you need an image node (the scene where a model will be placed) and geometry node (the model to place).

Let’s start with simple Read (Image) and ReadGeo nodes. First we select a footage or a still image for Read (Image) node, then a 3D model for ReadGeo node.

Note: PinTool supports rigged geometry which can be imported into Nuke using KeenTools ReadRiggedGeo node.

Then we connect Read (Image) to bg input and ReadGeo to geo input of PinTool.

Basic PinTool Setup

Using of cam (camera) input is optional. If you have a set up Camera (3D) node you can connect it to cam input of Pintool, so it will use all the parameters of the Camera (3D) node. You can also select custom constant/varying focal length in PinTool’s settings and set the custom Focal Length in the field below the drop-down menu, adding keyframes for each frame where the Focal Length is changing. And finally you can ask PinTool to estimate the Focal Length in case you don’t know what it was. Estimation starts when you click the checkbox in PinTool’s toolbar and start pinning your model. When you select custom constant focal length, estimation is changing global Focal Length which will be used for all the frames of the input video. Also, it’s worth mentioning, that when this constant Focal Length is being changed PinTool will automatically try to adjust positions of all the pins you have set in other frames so they will match the new Focal Length. When varying focal length is selected, estimation works for the current frame only not affecting any pins in other frames.

Note that if you don’t connect any camera node to PinTool default camera parameters are going to be used, except the Focal Length that you can change right in PinTool settings.

Another thing to mention is that it’s always better to remove lens distortion from the video before you feed it into PinTool. You can use LensDistortion node and reference checkerboard image in Nuke to un-distort your source footages and images.

Placing a model

When PinTool is supplied with geometry and image data you can start placing a model.

Before you start pinning your model, it’s usually better to find a frame where the image part that resembles the model is clearly visible and could be easily matched with the model.

Placing a model into the view

When the best matching frame is found press Center Geo button on PinTool’s toolbar. It will scale your model and place it in the center of the frame. Then you can start pinning: choose the most peculiar parts of the geometry and image, click on the geometry — the right square dot will appear, then drag it and attach it to the image. It’s totally fine to adjust positions of pins that were already placed. You can remove pins with right mouse click.

In case you want to remove all pins (they are all shared between frames) — use Remove Pins button on the toolbar.

Pinning process

A very helpful feature of PinTool is hidden behind the Magic Keyframe button on the toolbar which purpose is to automatically place a model.
Usually, if you have a good model, a detailed image, all the camera parameters are set correctly and you roughly placed the model, after pressing this button your model will be snapped to the image with very good quality. Sometimes it might even work without initial placement of the model, just don’t forget to click Center Geo before you click the Magic Keyframe button. The preciseness of automatic placement is growing with number of keyframes that were set previously. So, if it didn’t work for you the first time, you can try to place the model manually and try Magic Keyframe in the next frame where the position of the model needs to be adjusted.

Spring Pins Back checkbox changes the behaviour of pins. When on, PinTool will try to retain the pin on the mesh at any cost. When model is not precise or you can’t find any peculiar features of a model or a picture, you most likely want to keep this checkbox on and work on an iterational basis, slightly modifying the model’s position with a lot of pins. But when you have very precise model and you can spot a number of very precise features, you might try to set the checkbox off and then place your pins right where they should be — PinTool will not try to drag them back to the model. The point of working with Spring Pins Back set to off is that you know precisely where some features of the model should be on the picture — and so, you know that when you set enough pins, the model will be placed precisely and pins will be back on the model.

When you’re placing a model you might want to lock movement or rotation for some axes. You can use Fixed checkboxes on the main tab of PinTool’s settings.
rx, ry and rz lock rotation, while tx, ty and tz lock translation (i.e. movement). These checkboxes might be especially helpful during tracking process.

If you’re working with rigged geometry imported with ReadRiggedGeo node, you can also lock movement and rotation of different bones that the geometry has. Translation usually is locked by default, so if you want to unlock it, find a bone in the list of bones which appears on the main tab of PinTool when you connect rigged geometry, then find the column of the axis you need (tx, ty or tz, where t means translation), next to it you’ll find the column with locking checkboxes — uncheck the checkbox in the row of the bone you want to set free. Alternatively, if you want to restrict rotation of a bone — just find it in the list of bones, find the column of the axis you need and the locking checkbox nearby.

Underneath the list of bones you can find a couple of buttons that might be useful to lock and unlock rotation and translation of a bone along all axes. You can select more that one bone in the list and (un-)lock them all. Fix selected completely locks selected bones. Unfix selected unlocks rotation and translation of all selected bones and all axes. Reset selected unlocks rotation and locks translation.

Simple tracking

Using either manual or automatic model placement you can track the model movements across all frames of a footage.

Every time you move a pin or press the Magic Keyframe button on a new frame of a footage, a keyframe is being set. Sometimes it’s necessary to change the object’s position in every single frame, for example, in very dynamic footages with a lot of fast movement. Sometimes you can skip frames and set keyframes for let’s say every 10th frame or even less frequently.

When you have a number of keyframes among which a model is rotating for more than 360°, we recommend using the Unbreak Rotation button. The algorithm behind it will go through all of your keyframes and will make the rotation continuous. So if your model was at 355° at the keyframe #24 and at 10° at the keyframe #25, pressing the button will add 360° to the keyframe #25, so the model will be rotated at 370°. It works backwards as well: 355° after 10° will become -5°.
Considering that the Unbreak Rotation algorithm alters the rotation of object with the closest period (180°), you have to be careful if your model rotates forwards and backwards between keyframes — then the Unbreak Rotation button will most likely make things worse.

Sometimes you want to move your 3D model across the frame without changing it and without losing the pins that you have. In that case you can use Disable Pins button on the toolbar, it will lock positions of pins relative to each other so the model will be frozen. Then you can drag the model with one of the existing pins or create a new one and drag with it. Adding or clicking another pin will allow you to scale and rotate the model.


The output of the PinTool node is transformed geometry, you can use it like you use ReadGeo or TranfromGeo nodes.

Also, you can export geometry transformations as TransformGeo node. To do this, select TransformGeo in the drop-down of the Export section of PinTool’s main tab. Then press Export button. If you switch on Link Output, the exported TransformGeo will be linked to PinTool node and all the changes applied to PinTool node after exporting will be transferred to the exported TransformGeo node. If you don’t need this kind of behaviour, uncheck Link Output.

In addition to exporting geometry, you can export cameras. You have two options: simple Camera (3D) node or Tracked Camera. Both might be linked to PinTool to receive updates.
Exporting simple Camera (3D) node makes sense only if you need camera settings estimated by PinTool during model placement. If you imported camera settings into PinTool from another Camera (3D) node and used all its settings, there’s no point in exporting a Camera (3D) node from PinTool — just use the camera node you connected to PinTool previously.
Exporting Tracked Camera gives you a Camera (3D) node with all transformations stored keyframes you’ve created during manual tracking. If you used a camera node to setup camera in PinTool, all settings will be taken from that camera node (either by linking a new exported camera node to the old one if you switch on Link Output, or by copying the parameters).

When working with rigged geometry, you can also export TransformRiggedGeo node which will contain transformations of rigged geometry. More than that, you can export a TransformGeo node for each bone — exported node will contain transformations of one single bone you’ve exported.


Download KeenTools package for Nuke
Follow us: FaceBook, Twitter, Instagram, YouTube

PinTool in action