cgcookie / retopoflow

A suite of retopology tools for Blender

RetopoFlow

RetopoFlow is a suite of fun, sketch-based retopology tools for Blender from Orange Turbine that generate geometry which snap to your high poly objects as you draw on the surface.

This documentation covers the installation and usage of all tools included in the add-on.

You can read about the features and purchase a copy on our website or the Blender Market.

If you’re brand new to RetopoFlow, check the Quick Start page. Otherwise, jump right over to the Table of Contents.

Requirements

Below is a table showing which versions of RetopoFlow and Blender are compatible.

RetopoFlow	Blender
3.4.0	3.6 or later
3.3.0	2.93--3.5
3.2.4	2.8x--2.9x
2.0.3	2.79 or before

All versions of RetopoFlow will work on any operating system the Blender supports.

Downloading

Future updates to RetopoFlow are funded by Blender Market purchases, and we provide top priority support through the Blender Market. However, we also made RetopoFlow accessible on RetopoFlow's GitHub Page, especially for students, teachers, and those using RetopoFlow for educational purposes.

You may download RetopoFlow from your account dashboard on the Blender Market once you have already purchased it or from RetopoFlow's GitHub Releases Page. For the more techie crowd, you can also symlink a clone of the GitHub repo to your add-ons folder.

Important: Blender has issues with the zip files that GitHub automatically packages with the green Code button on the main GitHub page. Do not use the zip files created by GitHub. Instead, use the officially packaged versions that we provide through the Blender Market or the GitHub Releases Page.

The code for RetopoFlow is open source under the GPL 3.0 license. The non-code assets in this repository are not.

Installing

The easiest way to install RetopoFlow is to do so directly within Blender. You can do this by going to Edit > Preferences > Add-ons > Install. This will open a File Browser in Blender, allowing to you navigate to and select the zip file you downloaded. Press Install from file.

If your browser auto-extracted the downloaded zip file, then you will need to re-compress the RetopoFlow folder before installing, or use Save As to save the zip file without extracting the contents.

Once installed, Blender should automatically filter the list of add-ons to show only RetopoFlow. You can then enable the add-on by clicking the checkbox next to 3D View: RetopoFlow.

If you have any issues with installing, please try the following steps:

1. Download the latest version of RetopoFlow for your version of Blender (see Requirements section above).
2. Open Blender
3. Head to Edit > Preferences > Add-ons and search for RetopoFlow
4. Expand by clicking the triangle, and then press Remove
5. Close Blender to completely clear out the previous version
6. Open Blender and head to preferences again
7. Click Install
8. Navigate to your RetopoFlow zip file (please do not unzip)
9. Click Install Add-on
10. Enable RetopoFlow

Updating

RetopoFlow 3 comes with a built-in updater. Once you've installed it the first time, simply check for updates using the RetopoFlow menu. If you need to update the add-on manually for any reason, please be sure to uninstall the old version and restart Blender before installing the new version.

The RetopoFlow updater will keep all of your previous settings intact. If you need to update manually for whatever reason, you can also keep your preferences by copying the RetopoFlow_keymaps.json and RetopoFlow_options.json files from the previous version's folder before installation and pasting them into the new version's folder after installation.

See the Updater page for more details.

Getting Support

Here are ways to get help with a problem or a question that the documentation isn't answering:

• Get high priority support from Orange Turbine by sending a message from your Blender Market inbox once you've purchased a copy.
• Create a new issue on RetopoFlow's GitHub page.
• Reach out to us via email at [email protected].

Please provide as much information and detail as possible, such as steps to reproduce the issue, what behavior you expected to see vs what you actually saw, screenshots, and so on. See Debugging for details on getting as much useful information as possible. Also, if possible, please consider sending us the .blend file.

Contributing

Pull requests are welcome! If you'd like to contribute to the project then simply fork the repo, work on your changes, and then submit a pull request. We are quite strict on what we allow in, but all suggestions are welcome. If you're unsure what to contribute, then look at the open issues for the current to-dos.

retopoflow's Issues

Updating gedges with fixed counts is jumpy

When gedge has fixed segment count, updating (by moving a gvert) can cause the segmentation to act erratically and cut non-uniformly.

Mesh extension: selecting multiple edges colors existing mesh green.

If you select multiple edges with an existing mesh then the whole existing mesh turns green. Likely just a color targeting issue.

GVert is left-handed!

this mistake was made early on in dev (much of the framework uses this) and needs to get fixed.

Add a Face Loop selection tool

Allow user to select a faceloop with ALT+SELECTMOUSE:

do visibility tests on gpatch

Only active strip is highlighted when multiple strips are selected.

When selecting multiple strips for filling only the active strip is highlighted.

Active should draw with theme_colors_active color, selected should draw with theme_colors_selection color.

Polystrips on thin areas often flip to the wrong side

We've talked about this one before, and so far as I know there's no good solution at the moment but it's something we should kind in mind to investigate.

On thin models there's often a problem with polystrips flipping to the opposite side of the mesh from that which it's drawn on. This can be really troublesome for certain models.

Undo not restoring selected gedges properly

undo snapshots do not copy/restore the sel_gedges set

add F2-like simple fill

select cornered gvert or two gedges that meet at a corner

Do not modify the sys.path

need to use relative paths with import

Make Contours use common functions where applicable

Contours still has a good few function calls that can be changed out for our common functions in lib.

Should not be able to scale inner gverts

Current you can scale a selected inner gvert. This is unnecessary and should not be allowed, so as to prevent confusion with the user.

If an inner gvert is selected let's not allow the scale operator to be activated.

Make Patches use minimum segment count rather than max

remove draw_callback_debug function

Support filling patches alongside existing geometry

We need to support creating patches alongside existing geometry. Like this:

Currently we get this (gedge pulled out to showcase problem):

Keymaps should be created as a Modal Keymap

The hard-coded keymaps are really troublesome right now, particularly for selection. They aren't flexible and are easily missed if we forget to update the header.

According to @ideasman42, it should be possible to define an actual modal keymap in Python, like this:

Update Readme for 1.1.0 release

Add a Relax tool

Extending a gedge from existing gedge uses brush size, should inherit size from existing gedge

If you extend a gedge from an existing gedge (creating a new gvert at the the stroke start) then it uses the brush size. This causes unwanted scaling of the original gedge.

Solution: inherit the size for the first gvert in the new gedge from the size of the original gedge.

UI checkbox to turn off pressure

Need to add the ability for users to turn off pressure sensitivity. It's not always useful and some users will want to use a tablet but not use pressure.

If Use Pressure is enabled then strokes always start small

When using a tablet, if Use Pressure is enabled, then the start of the stroke is always small. No matter how large the initial pressure push.

UI: always draw panel and display error message upon invoke if requirements not satisfied

Always draw panel and display error message upon invoke if requirements not satisfied

occlusion lost when segment count changes

When using simple fill, changing the segment count of GEdge causes all occluded geometry to be visible through object.

Selected and Active Gverts are reversed

This still needs confirmed, but it seems that the Active and Selected Gverts status is reversed.

Add a Tweak move tool

Optimize Polystrips for speed

Polystrips can quickly become quite slow, particularly on slower machines and complex models.

If there's anything we can do to optimize it then we should 😄

Speed is probably one of the more common points of critical feedback I've heard.

Unify selection sets

Currently selection is split across gverts, gedges, and gpatches. Per discussion, we've decided to unify this such that all elements belong to the same selection set.

Contours is broken: sequence size is 2, expected 3

Traceback (most recent call last):
  File "/Users/jonathanwilliamson/Dropbox (Personal)/blenderDev/addons/cgCookie/scripts/addons/retopoFlow/__init__.py", line 1310, in modal
    self.hover_loop_mode(context, settings, event)
  File "/Users/jonathanwilliamson/Dropbox (Personal)/blenderDev/addons/cgCookie/scripts/addons/retopoFlow/__init__.py", line 893, in hover_loop_mode
    h_target = c_cut.active_element(context,event.mouse_region_x,event.mouse_region_y)
  File "/Users/jonathanwilliamson/Dropbox (Personal)/blenderDev/addons/cgCookie/scripts/addons/retopoFlow/contour_classes.py", line 2459, in active_element
    intersect = intersect_point_line(mouse_loc, a, b)
ValueError: intersect_point_line: sequence size is 2, expected 3

Simple Fill should draw with transparent faces.

The simple fill areas should fill with partially transparent faces to improve the visibility. Currently only the wireframes are drawn.

Split preferences into own file

To help keep files condensed I suggest we split off the add-on preferences into it's own file.

Occasionally tweak will rip verts away from patches

code uses sel_gvert and act_gvert incorrectly

sel_gvert should probably be the set sel_gverts

Re-work widget theme and options

The Contours widget needs to be re-designed and re-themed. The new design has been done by Pawel L. but the functionality is waiting on the new Wiggly Widgets work by Antony R in Blender master.

Add support for Patches alongside T-Junctions

Allow Gverts to be merged into Gverts that're patched

We don't currently allow the user to merge a gvert into another gvert that is part of a patch. Assuming the target gvert has open sides then we should allow this.

If an gedge is selected then all gverts are drawn in selected color.

Replace old settings calls with new function in common_utilities

Contours used an older method of setting the add-on preferences. We now have a common utility that makes it much simpler.

All calls for:

settings = context.user_preferences.addons[AL.FolderName].preferences

Should be replaced with:

settings = common_utilities.get_settings()

CTRL+Click extrude does not work across clipping plane

If you Shift+Click extrude a gvert across the clipping plane it does not work. It gets tossed completely without an error.

selecting corner gedges should test if new gvert needs to be created

If a GEdges fully exist to make a GPatch, selecting two adjacent GEdges will cause simple fill to create another GVert.

Explicit Imports only please

remove instances of from my_lib import *

-reduces readability
-imports things indiscriminately of need

Selection should be based on User Preference Select Mouse

We should auto-detect which mouse the user has specified for selection and use that in both Contours and Polystrips for selection.

Hints here: http://blender.stackexchange.com/questions/21708/is-it-possible-to-create-a-modal-operator-with-a-modal-keymap-in-python

Repot theme can be a bit hard to see, needs adjusted

Let's make the theme a bit brighter to help with the visibility in areas of the mesh with specular highlights.

Tweak: adjusting segments in gedge adjacent to tweaked patch makes everything disappear momentarily

If you tweak a patch and then try and adjust the segments of an adjacent gedge it breaks. Everything but the tweaked patch disappears.

Console output:

Traceback (most recent call last):
  File "/Users/jonathanwilliamson/Dropbox (Personal)/blenderDev/addons/cgCookie/scripts/addons/retopoFlow/__init__.py", line 2214, in draw_callback
    return self.ui.draw_callback(context)
  File "/Users/jonathanwilliamson/Dropbox (Personal)/blenderDev/addons/cgCookie/scripts/addons/retopoFlow/__init__.py", line 2505, in draw_callback
    self.draw_callback_themed(context)
  File "/Users/jonathanwilliamson/Dropbox (Personal)/blenderDev/addons/cgCookie/scripts/addons/retopoFlow/__init__.py", line 2550, in draw_callback_themed
    for (p0,p1,p2,p3) in gpatch.iter_segments(only_visible=True):
  File "/Users/jonathanwilliamson/Dropbox (Personal)/blenderDev/addons/cgCookie/scripts/addons/retopoFlow/polystrips.py", line 1296, in iter_segments
    if not all(self.visible[idx] for idx in lidxs):
  File "/Users/jonathanwilliamson/Dropbox (Personal)/blenderDev/addons/cgCookie/scripts/addons/retopoFlow/polystrips.py", line 1296, in <genexpr>
    if not all(self.visible[idx] for idx in lidxs):
KeyError: (11, 1)```

![screen shot 2015-01-03 at 10 28 39 pm](https://cloud.githubusercontent.com/assets/1648631/5604776/f6086094-9397-11e4-92e6-fb3b9bb5724c.png)
![screen shot 2015-01-03 at 10 29 26 pm](https://cloud.githubusercontent.com/assets/1648631/5604777/fd6338aa-9397-11e4-8952-9c873d9e1fac.png)

Note: the behavior is slightly different when increasing/decreasing segments.

Sometimes gverts remain highlighted during selection changes

Not able to narrow this down yet, but sometimes when selecting elements other gverts will remain highlighted.

Need function to clear selection sets

Polystrips fails on start if "BezierCurve" object exists

If a bezier curve object with name "BezierCurve" is present in scene upon starting Polystrips then it fails.

Traceback (most recent call last):
  File "/Users/jonathanwilliamson/Dropbox (Personal)/blenderDev/addons/cgCookie/scripts/addons/retopoFlow/__init__.py", line 2200, in invoke
    self.ui = PolystripsUI(context, event)
  File "/Users/jonathanwilliamson/Dropbox (Personal)/blenderDev/addons/cgCookie/scripts/addons/retopoFlow/__init__.py", line 2348, in __init__
    self.create_polystrips_from_bezier(bpy.data.objects['BezierCurve'])
  File "/Users/jonathanwilliamson/Dropbox (Personal)/blenderDev/addons/cgCookie/scripts/addons/retopoFlow/__init__.py", line 3678, in create_polystrips_from_bezier
    gv0 = pregv if pregv else self.create_gvert(mx, bp0.co, 0.2)
AttributeError: 'PolystripsUI' object has no attribute 'create_gvert'

Selecting patches leaves gverts of any selected edges highlights

If you select a patch while some gedges are selected then it leaves the gverts of those gedges highlighted, even though the gedges are no longer selected.

Cannot delete strip when part of patch

If a strip is part of a patch then it crashes upon trying to delete the selected edge.

Traceback (most recent call last):
  File "/Users/jonathanwilliamson/Dropbox (Personal)/blenderDev/addons/cgCookie/scripts/addons/retopoFlow/__init__.py", line 2213, in modal
    ret = self.ui.modal(context, event)
  File "/Users/jonathanwilliamson/Dropbox (Personal)/blenderDev/addons/cgCookie/scripts/addons/retopoFlow/__init__.py", line 3791, in modal
    nmode = FSM[self.mode](eventd)
  File "/Users/jonathanwilliamson/Dropbox (Personal)/blenderDev/addons/cgCookie/scripts/addons/retopoFlow/__init__.py", line 3388, in modal_main
    self.polystrips.disconnect_gedge(self.act_gedge)
  File "/Users/jonathanwilliamson/Dropbox (Personal)/blenderDev/addons/cgCookie/scripts/addons/retopoFlow/polystrips.py", line 1191, in disconnect_gedge
    gedge.disconnect()
  File "/Users/jonathanwilliamson/Dropbox (Personal)/blenderDev/addons/cgCookie/scripts/addons/retopoFlow/polystrips.py", line 601, in disconnect
    self.gvert0.disconnect_gedge(self)
  File "/Users/jonathanwilliamson/Dropbox (Personal)/blenderDev/addons/cgCookie/scripts/addons/retopoFlow/polystrips.py", line 135, in disconnect_gedge
    self.update_gedges()
  File "/Users/jonathanwilliamson/Dropbox (Personal)/blenderDev/addons/cgCookie/scripts/addons/retopoFlow/polystrips.py", line 191, in update_gedges
    self.update()
  File "/Users/jonathanwilliamson/Dropbox (Personal)/blenderDev/addons/cgCookie/scripts/addons/retopoFlow/polystrips.py", line 256, in update
    if gedge: gedge.update()
  File "/Users/jonathanwilliamson/Dropbox (Personal)/blenderDev/addons/cgCookie/scripts/addons/retopoFlow/polystrips.py", line 938, in update
    gpatch.update();
  File "/Users/jonathanwilliamson/Dropbox (Personal)/blenderDev/addons/cgCookie/scripts/addons/retopoFlow/polystrips.py", line 1121, in update
    lc0 = list(self.ge0.iter_segments())
  File "/Users/jonathanwilliamson/Dropbox (Personal)/blenderDev/addons/cgCookie/scripts/addons/retopoFlow/polystrips.py", line 984, in iter_segments
    cur0,cur1 = gv0.get_corners_of(self)
  File "/Users/jonathanwilliamson/Dropbox (Personal)/blenderDev/addons/cgCookie/scripts/addons/retopoFlow/polystrips.py", line 356, in get_corners_of
    assert False, "GEdge is not connected"
AssertionError: GEdge is not connected

Fill should display error if no edges selected

If no gedges are selected then an error message should be displayed.

Sometimes gedges draw as selected when they're not

This generally happens after having multiple gedges selected and then changing selection to just one gedge.

The sel_gedges likely isn't getting cleared.