Deprecated: Function set_magic_quotes_runtime() is deprecated in /storage/content/76/1004576/ on line 33 Deprecated: Function split() is deprecated in /storage/content/76/1004576/ on line 95 Deprecated: Function split() is deprecated in /storage/content/76/1004576/ on line 743 docs:04reference [DokuWiki]

JPatch 0.4 modeller reference manual

The main window

The main toolbar

The main toolbar contains buttons to create, load, or save a model. The rest of the buttons are used to manipulate the view or change the behavior of the viewports.

New, Open and Save

New lets you start a new (empty) model, Open will open a filechooser to load a model from disk, and Save will save the model to disk. If the model was loaded from disk before, it will be saved under the same name (the old file will be overwritten), otherwise JPatch will ask for a filename. If you want to save the model to a different file, use Save as… from the File menu.


You can switch between single-, horizontally split-, vertically-split- and quad-viewport mode. The active viewport has a yellow border around it. You can activate a viewport by clicking any mousebutton inside it.

Rotate, Move or Zoom view

Lets you rotate, move or zoom the view. Click one of the buttons, move the mousepointer over a viewport, click the left mousebutton and drag.

Zoom to fit

This will adjust the view of the currently active viewport to show the currently selected part of the model, or (if nothing is selected), all visible (not hidden) parts of the model.

Undo, Redo

Will undo the last operation or redo the last undo respectively. You can undo up to 30 operations. Redo only works if no other operation has been performed in the meantime. Note that changing the selection is an undoable operation.


When active, positions on the X-, Y- or Z-Axis will be locked.

Snap to grid

Toggles grid snapping

Hide unselected points

Toggles hiding of unselected points.

The main menu


Lets you open a new model, load a model from disk, save the model to disk, export to different file formats or quit the application.

  • New: removes everything and starts a new model.
  • Open (new): will clear the current model before loading a new one.
  • Open (append): will keep the current model and append the new one to it.
  • Save: saves the current model.
  • Save as: saves the current model to a new file (opens a filechooser).
  • Import → sPatch: imports a model in sPatch format.
  • Import → Animation:Master: imports a model in Hash’s Animation:Master format.
  • Export → Alias|Wavefront: exports in .obj format. A dialog will ask you for:

  • The filename.
  • The output mode: triangles or quadrilaterals.
  • The mesh density (in quads per patch).
  • Wheter or not to export surface normals.

See also Bicubic Patch or Triangle/Quadrilateral output.

  • Export → POV-Ray: exports the model to a POV-Ray include file. A dialog will ask you for:

  • The filename.
  • The output mode: triangles (mesh2) or bicubic patches.
  • The mesh density (in quads per patch).

See also Bicubic Patch or Triangle/Quadrilateral output.

  • Export → RenderMan: exports the model to a RenderMan .rib file. A dialog will ask you for:

  • The filename.
  • The output mode: triangles, quadrilaterals, subdivision surfaces or bicubic patches.
  • The mesh density (in quads per patch). This settings has no relevance if the output mode is bicubic patches.

See also Bicubic Patch or Triangle/Quadrilateral output.

  • Quit: quits JPatch


  • Synchronize viewports: Normally, when editing the model, only the active viewport will be updated until the mousebutton is released. Activating Synchronize viewports will always update all viewports. This is only recommended on fast machines.
  • Colors: lets you modify your color preferences.
  • Grid spacing: sets the grid spacing
  • Render settings: In the dialog you can set the tesselation quality and the backface mode:
  • do nothing doesn’t make a difference between front- and backfacing patches.
  • cull does not render backfacing patches.
  • highlight highlights backfacing patches (you can specify the color in the colors menu).

These settings do not affect the quality of exported models!

  • Light: switches between no light (fastest), simple, head- and three-point-light (slowest). Stick to camera toggles wether the lights should rotate with the camera or not.
  • Look and feel: lets you switch between different Java Swing look and feels


  • Dump: dumps information about the current model to the console (for debugging purposes).
  • Dump undo stack: dumps the content of the undo/redo stack to the console (for debugging purposes).
  • Check model: runs some tests to check the model integrity and dumps the result to the console (for debugging purposes).
  • Edit phoneme-morph-mapping: let’s you edit the mapping from phonemes to morphs. This experimental feature is used by the JPatch Animator for lip-syncing using JLipSync or MagPie timesheets.


  • About: displays information about the version, license, acknoledgements and thanks.

The viewports

In the upper left corner of a viewport, the view directien (front, side, top, bird’s eye, etc.) is displayed. The nuber below tells how long (in milliseconds) it took to render the image in this viewport. If this number gets high, JPatch will become less responsive - you should change the rendering quality or lighting mode then.

In the upper right corner of a viewport some symbols may be displayd: A Z means that the z-buffer renderer is in use (else the Java2D renderer is used). The hash symbol (#) represents the grid - it is displayd when snap-to-grid is turned on. The lock symbol tells that the viewport is “locked” to a selection. Normally, when when rotating the view, it is rotated around the origin. Sometimes its desired to rotate around another point - e.g. when modeling details on a characters hand, you’d like to be able to rotate the camera around the hand quickly, to see it from different directions. You can lock the view to the hand, so rotating the view will rotate it around the center of the selection (also called pivot).

In non-bird’s-eye view a grid is shown. The origin is shown as a little cross, the red line represents the X-axis, the green the Y-axis, the blue the Z-axis (X,Y,Z … red,green,blue).

The “compass” in the lower left corner shows the axis and their directions again.

You can modify the view (translate, rotate or zoom) or modify the model by clicking on one of the tool buttons in the main- or mesh-toolbar and using the left mousebutton inside the view.

The right mousebutton will open a popup menu (see below).

The scrollwheel can be used to zoom, and the middle mousebutton to move the view (hold and drag). If the middle mousebutton is pressed over the compass, dragging will rotate the view. If the viewport is locked to a selection, dragging with the middle mousebutton down will also rotate the view.

Whenever a mousebutton is pressed over a viewport, it becomes active (it has a yellow border around it). Some commands will affect the active viewport only.

The edit toolbar

The edit toolbar contains all tools to manipulate a model.

Default tool The default tool can be used to select points, move points or selections and scale selections. To select a single point, simply (left) click on it. To move a point, select it and drag with the left mousebutton still down. To select multiple points, press the left mousebutton (not over a point), drag to draw a selection rectangle, and release the button. All points under the rectangle will be selected. The selection is shown as a yellow box. To move a selection, simply press the left mousebutton inside the yellow box and drag. To scale the selection, move one of the scale handles (the little yellow boxes in the corners of the selection box). The scaling will be relative to the pivot (normally the center of the selection). The pivot can also be moved (it’s the little yellow box with the red/green/blue axis marker). When making selections, you can use the SHIFT key to add the new selection to the current one, or the CTRL key to remove the new selection from the current one. Pressing (and holding) the ALT key before moving a point or a selection will move perpendicular to the screen plane. This is useful when working with multiple viewports. When moving a single controlpoint, the controlpoint can be welded to another controlpoint by moving it over the target point and clicking the right mousebutton.

Add point Press the left mousebutton to start a new curve segment, drag the mousepointer to the end of the curve segment and release the button. You can append an existing curve by starting the new segment at one end of an existing curve. You can also use the right mousebutton to weld the endpoint, just like with the default tool (see above). After the left mousebutton was released JPatch switches back to the default tool. If you’d like to stay in add point mode you can use the Add multiple points tool.

The right mousebutton can also be used to add so called hooks. Normally, points are welded onto other points. But it is also possible to hook a point on a curve segment, at positions 1/4, 1/2 and 3/4. Move the point over the curve and (with left mousebutton still down) click the right button (just like when welding). There are some examples that show how hooks can be used in the tutorials…

Rotate tool: When multiple points are selected, click on the rotate tool to rotate the selection. The rotate tool is a sphere, made of four circles. You can press the left mousebutton and drag inside the sphere to rotate freely. If you move one of the handles, the rotation is constrained to the axis the handle belongs too (red, green, blue for x,y,z, yellow for the axis perpendicular to the screen plane). The rotations snaps to 5° steps unless SHIFT is pressed. Rotation is performed around the pivot (the center of the sphere), which can be moved. Doubleclick the pivot to reset it to the selection’s center. Doubleclick any handle to reset the coordinate system back to x/y/z. If you hold the control CTRL key down, only the rotate tool will be rotated (not the selected points). This is useful when you’d like to rotate around a certain axis - you can position the rotate tool as desired by holding down CTRL, and then perform the rotation.

Magnet tool: Use this tool to move multiple points. Click and drag to set the size of the tool (the radius of influence), then select a point and move it. All other points within the radius of influence will be moved as well, depending on their distance to the magnet.

Rotoscope tool: When the viewport has a rotoscope (background image) set (via the popup menu), this tool can be used to move or scale the background image or to set its opacity.

Tangent tool: This tool can be toggled on or off. When it’s on, and a single point which is not attached, or a curve segment is selected, two tangent handles will appear. These can be moved to change the magnitude (or curvature). To select a curve segment, first select a single point, and then hit the TAB key until the desired segment gets highlighted (green).

Peak and round mode: This will change the tangent mode of all selected controlpoints (or only the selected curve segment) to peak or round. It also sets the tangent mode for all points that will be added in future.

Detach points: Select an attached point and press this button to detach it.

Copy: Select some points and click this button to copy the selection. Note the new selection named “clone #number” in the selections tree (in the sidebar). Don’t forget to move the copied selection. If you clicked outside the selection by accident, select it again from the selection tree. Theres a common pitfall: After moving the copied selection, clicking undo will only undo the move. You’ll have to click undo again to undo the copy operiation as well.

Extrude: Works just like copy, but the copied points will be connected to the original ones.

Lathe: The selected points will be lathed around the Y-axis. A dialog will ask for the number of segments, 8 is the default. Points on (or very close) to the Y axis will be treated specially, i.e. the caps will be closed. Just like copy and extrude, lathe will add the now object to the selections.

Make five point patch: JPatch will recognize all 3- and 4-sided patches. To make a five sided patch, select all corners and click on this button.

Compute patches: Right now, creating 3- and 4-sided patches is not performed dynamically. You have to use this button to make JPatch compute the patches.

The popup menu

The popup menu is divided in tow parts. The upper part contains tools that affect the current viewport only. The lower parts contains tools I have moved to the popup menu for faster access.


You can toggle the display for points, curves, patches and bezier-controlpoints (the latter are for debugging purposes only). When patches display is turned on JPatch will automatically switch to the z-buffer rendering mode. Do not use this on remote connections (x-windows, terminal-server, VNC, etc.)!


Switch the view between front, rear, top, bottom, left, right and bird’s eye. Grid display and grid snapping do not apply to the bird’s eye view.


You can set or clear a rotoscope (background image). The background image can moved and scaled using the rotoscope tool from the mesh toolbar.

lock to selection/unlock

If multiple points are selected (the yellow selection box is visible), you can lock the view to the center (pivot) of the selection. When locked, a little lock symbol will appear in the upper right corner of the viewport. Rotating the view will now rotate around the selections pivot (not the origin), and the middle mousebutton will rotate (not move) the view. The view will be unlocked if you use the move- or zoom-to-fit-tool from the main toolbar.

always use z-buffer

If selected, the z-buffer renderer will always be used (normally, when show patches is turned off, JPatch will use Java2D to render the model). A little Z will appear in the upper right corner of the viewport if the z-buffer renderer is used.


select none

Deselects everything

select all

Selects all visible controlpoints (see Hide unselected points in the Main Toolbar)

invert selection

Inverts the current selection (taking only non hidden controlpoints into account. See Hide unselected points in the Main Toolbar)

extend selection

When a single point on a single curve or a curve segment is selected, the selection will be extended to the entire curve. In all other cases, the selection will be extended to all connected points.

clear patches

Removes any assigned materials from all selected patches. This effectively prevents the patches from being exported to the renderer. If you’d like the patches to be exported to the renderer again, simply assign materials.

align patches and flip patches


Flip X/Y/Z

Flip the selection on the selected axis (using the selection’s pivot).

Align controlpoints

Opens a dialog window asking for an axis and a position. The default (X-axis, potision 0) will set the x-component of all controlpoint position to 0 (thus align the points to the Y/Z plane). This is useful e.g. for the auto mirror tool.

Auto mirror

Mirrors the model on the Y/Z plane. You can e.g. model half of a character (either the left or the right side) in front view and then use auto mirror to complete the model. It will not only mirror the model, it will also connect the two halfes on the Y/Z plane. For this to work, it is important that the points that should be connected are aligned exactly on the Y/Z plane (their x component must be 0). You can use the Align controlpoints tool to achive this.


You can change the tangent mode of the selected controlpoints to peak, round (JPatch) and round (sPatch). Peak and round (JPatch) are equal to the modes which can be set by using the peak/round buttons in the mesh toolbar. The JPatch mode is not backward compatible to the mode used in JPatch versions prior to version 0.3 (which is the same as in sPatch and hamaPatch). The sPatch mode is set automatically for all poins in a model imported from sPatch format.

The sidebar

The sidebar contains a field for manually entering coordinates (currently deactivated), the tree-view, and a button panel (depending on the selected tree element).

Selections: The tree view contains models (currently only one model is supported) as roots, and selections and materials as branches. You can add a selection by first selecting the controlpoints (with the default tool from the mesh toolbar), clicking on the Selections node in the tree and clicking on the Add current selection button. To access the selection later, simply click on its node in the tree. When it is selected, you can also rename or delete it from the tree. To hide away unwanted parts use the hide button from the main toolbar. E.g. if you have a model of a head and like to change a detail on the eye, select the eye and click on the hide button: Everything but the eye will be hidden. Click on the hide button again to show everything again.

Materials: You can add a new material by selecting the Materials node in the tree and clicking on New material. Select the material node in the tree to edit, delete, apply or select it. Edit will open the material editor, Delete will delete the material, Apply will apply the material to all currently selected patches and Select will select all patches with the current material.

Expressions: You can add new morphs here. Adding a new morph does automatically switch into Edit Morphs mode. In this mode, only a subset of the modeling tools is available (you can modify the existing mesh, but not add or remove controlpoionts). The end editing the morph (and switch back to the default mode), click on the edit button to deselect it. You can select any morph under the Expressions branch of the tree. You can edit or delete it (by clicking on the edit or the delete button). You can also change the name of the morph, change it’s max and min values (usually 0.0 and 1.0) and test the morph by using the slider.

The material editor

Select a material and click on the edit button to start the material editor. Use the sliders to change the color and other properties of the material. The window on the upper right side will show how the material looks when applied to a sphere. Click and drag inside this window to change the camera position. The tabs in the lower part of the material editor can be used to edit how the material will be exported to POV-Ray, RenderMan or Inyo: The variables (starting with a $-Symbol) are substituted by the corresponding slider values. You can also use $reflection (the average of reflection_min and reflection_max) and $opacity (the opacity color computed using color, transmit and filter). In the caso of Inyo, if the field is empty, JPatch will automatically export all material properties (color, finish, etc.) to Inyo. Alternatively, you can enter a filename of a beanshell [.bsh] file that contains the material definition.

Keyboard commands

The table below shows the keybord mapping:

Single view 1 Delete points BACKSPACE
Horizontal split view 2 Compute patches F5
Vertical split view 3 Copy CTRL-C
Quad view 4 Extrude E
Rotate view SHIFT-R Lathe L
Move view SHIFT-M extend selection ENTER
Zoom view SHIFT-Z Next curve TAB
Undo CTRL-Z Insert point INS
Redo CTRL-Y bottom view NUM0
Lock/unlock X X front view NUM2
Lock/unlock Y Y right view NUM4
Lock/unlock Z Z top view NUM5
Default tool ESC left view NUM6
Add point A bird’s eye view NUM7
Add multiple points SHIFT-A rear view NUM8
Magnet tool M Snap to grid G
Rotate tool R Hide/show unselected points H
Remove points DEL

Inserting and deleting controlpoints

The commands Next curve [TAB], Insert point [INS], Remove points [DEL] and Delete points [BACKSPACE] are only available via the keyboard commands.

  • Next curve [TAB] is used to select a curve segment. Select a point and press the TABULTOR key until the desired curve segment gets highlighted.
  • Insert point [INSERT] will insert a point on the selected curve segment.
  • Remove points [DEL] will remove all selected points. Curves will be reconnected.
  • Delete points [BACKSPACE] will delete all selected points. Curves will not be reconnected.


Bicubic Patch or Triangle/Quadrilateral output

JPatch can now output two different representations of the patch-meshes:

  1. Bicubic Bèzier patches
  2. Hash-Patches, tesselated into a triangle or quadrilateral grid

Bicubic Patches

The advantage of the Bèzier Patches is that they are directly supported by POV-Ray and Render-Man, so the geometry files generated by JPatch are relatively small. The disadvantages of the current implementation are:

  • Cracks or creases in the surface on non-foursided patches or when hooks are used
  • Flat-spots in the surface, because the twist vectors (represented by the inner 4 controlpoints of a patch) are all set to 0


The advantages of the triangle- or quad- output are:

  • Cracks caused by hooks are detected and closed
  • Surface normals are recomputed to avoid creases and self-shadowing artifacts.

The disadvantages are:

  • Geometry files can be much larger (depending on the subdivision level)
  • To correctly recompute the surface normals, all patches must be aligned.

To take advantage of the REYES algorithm used by most Render-Man renderers, the quad-grid can be rendered as Catmull-Clark subdivision surface. In this case, the tesselation level in JPatch should be set to a low value (4 or 16) bacause further subdivision is done by the renderer.

Aligning patches

To support Triangle/Quad output patches should be aligned (even if it is not always required, it is still a good idea to align the patches anyway). Patches have a front- and a backside. Normally, the front side should face outwards (e.g. on a model of a human head). Unfortunately there is no way for JPatch to know which side is outwards, and at present the patch finding algorithm doesn’t even try to guess. This means that after running compute patches or after importing an sPatch or Animation:Master model, about 50% of the patches will be facing in the wrong direction.

To see which patches are facing the wrong direction, there is a new option in Renderer settings (in the main options menu) called Backface Mode. It has three options:

  1. do nothing
  2. cull
  3. highlight

Do nothing will display the patches as usual, so you can’t see whether a patch is facing the right direction or not. Cull will simply cull (not display) backfacing patches. Highlight will highlight backfacing patches using a solid color (per default red, but you can change that under Colors… in the main options menu).

Align patches and flip patches

There are two new tools in the popup menu that can be used to correct that. Flip patches will simply flip the selected patches. Align patches will try to align all selected patches so that neighboring patches face in the same direction. To correctly align all patches of a model, follow these steps:

  1. Ensure that Backface Mode (in Renderer settings) is set to cull or highlight, and that show patches (in the popup menu) is turned on.
  2. Select the entire model and run Align patches. If all went well, all connected patches should now face in the same direction. Note that it is still possible that this is the wrong direction, and that different not connected parts of the model face in different directions.
  3. Select a part that still faces the wrong direction: Select a controlpoint and hit the ENTER key twice - all connected controlpoints are now selected to. After that, use Flip patches from the popup menu. Repeat this step until all patches of your model face in the correct direction.

The align patches tool is now much better than in previous version, but there are still cases in which it can get confused:

  • If the topology contains Moebius strips
  • In some cases where hooks are used (I’m working on a fix for that problem)
  • If two or more surfaces intersect eachother, it will now follow each surface, but it is possible that the intersecting surface will face in the wrong direction afterwards.

There’s nothing that can be done about the first one: simply avoid such topologies. If you run into the second our third problem, the only option is to manually select all the patches that face in the wrong direction and flip them.

All in all I think with both tools it should be possible to align all the patches of a model in a matter of minutes, but I’m working on improvements, e.g. to automatically align all new patches and to further improve the auto-align feature.

How to select one or more patches

A patch is selected if all its corner-controlpoints are selected. Note that you can’t select a hook by clicking on it, but you can select it using the lasso. You can use the SHIFT key to add more points to the selection or the CONTROL key to remove points from the selection.

Notes on this release

  • The scale, rotate, pivot, and translate tabs above the tree are not functional.
  • The need to press F5 to compute patches will be replaced by a better, dynamic patch-finding solution.
  • JPatch is work in progress, and this release (JPatch0.4 preview 1) is just a preview of the upcoming version 0.4, it’s not thoroughly tested and some features are experimental (i.e. maybe unstable and not very userfriendly).

Related topics

  docs/04reference.txt · Last modified: 2005/11/22 10:45