KeenTools PinTool Tutorial
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
Note: PinTool supports rigged geometry which can be imported into Nuke using KeenTools
Then we connect
Read (Image) to
bg input and
geo input of PinTool.
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.
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.
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.
rz lock rotation, while
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 (
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.
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
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
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.
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.
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.