2025-07-01

2026-03-17 14:30:01 -06:00
parent f9a22056dd
commit 62b5978595
4579 changed files with 1257472 additions and 0 deletions
@@ -0,0 +1,25 @@
+# RetopoFlow Updater System
+
+Keep RetopoFlow up-to-date with the latest official releases using the updater system!
+
+1. Click the "Check for updates" button in the RetopoFlow menu.
+2. If the "Update now" button...
+
+    - stays disabled: no updates are ready at the moment.
+    - becomes enabled: click it to download and install the latest release of RetopoFlow.
+
+For those who would like to try the pre-releases or try out latest bug fixes, use the "Updater System".
+
+IMPORTANT: The RetopoFlow Updater System can break your RetopoFlow installation!
+To fix a broken RetopoFlow install, simply download and install the latest version from [Blender Market](https://blendermarket.com/products/retopoflow).
+
+![](images/addon_updater_button.png max-height:200px)
+
+The RetopoFlow Updater System will show the last 10 or so releases/pre-releases.
+Choose one of the releases then click the "Load" button to download and install that exact version.
+
+![](images/addon_updater_system.png max-height:400px)
+
+If you wish to try a specific branch or commit, specify the branch or commit hash in the "Advanced: Commit / Branch" text box, then click the "Load" button.
+
+![](images/addon_updater_advanced.png max-height:150px)
@@ -0,0 +1,266 @@
+# RetopoFlow Change List
+
+This document contains details about what has changed in RetopoFlow since version 2.x.
+
+### RetopoFlow 3.4.2&rarr;3.4.3
+
+- Fixed text rendering bug
+- Fixed GPU Capabilities bug with Blender 4.1
+- Fixed Blender UI becoming unresponsive after starting RF
+
+### RetopoFlow 3.4.1&rarr;3.4.2
+
+- Worked around issue of "locking" Blender interface on Windows machines with Blender >3.6
+- Strokes now shows counts for selected verts, selected edges, new spans, new loops
+- Improved clarity for target geometry that is pinned, seam, non-manifold
+- Disabling visualization of pinned or seam geometry will disable pinning
+- Added keymap for marking/clearing seams, confirming quick tools
+- Added keymap for confirming quick tools
+- Added Merge options to Delete / Dissolve pie menu
+- Many minor bug fixes
+
+### RetopoFlow 3.4.0&rarr;3.4.1
+
+- Improved visualization and editing when working on "wrong" side of symmetry
+- Fixed bridging bug with Strokes
+- Fixed many bugs
+- Improved general PolyPen performance
+- UI drawing uses framebuffers again (UI performance)
+- Warns when geometry is on "wrong" side of symmetry
+- General code cleanup, refactor, and optimizations
+
+### RetopoFlow 3.3.0&rarr;3.4.0
+
+This version of RetopoFlow requires Blender 3.6 or later.
+
+- Blender
+    - Removed dependence on deprecated `bgl` module
+    - Added support for Metal
+    - Improved general feedback and error handling during startup process
+    - Improved indication of warnings in Blender menu
+    - Added button to continue editing with active mesh as target
+    - Improved handling of when Blender version is outside requirements
+- Performance
+    - Improved navigating and selecting
+    - Improved performance of all tools
+- Select: added new tool to do box selection
+- General: added simple rip and rip fill
+- Contours
+    - Fixed crashing bug when cutting across non-manifold edge
+    - Fixed bug when cancelling cut
+- Strokes: consistent fixed span/segment count for all insertions
+- Knife: fixed bug when using where no source geometry exists
+- Tweak: added raycast/snap modes to work in screen or world space
+- Auto Save
+    - Fixed and improved reporting, recovery, and other operations
+    - Auto save is delayed until current action is finished
+- Input
+    - Added keymaps to select all linked, roll view, increase vertex count (Contours, PolyStrips, etc.) with `plus` key
+    - Fixed NDOF and trackpad
+- Mirror: preliminary work to mirror actions to "correct" side of symmetry plane(s)
+- Debug: deep debugging for capturing terminal output to a file
+- Hive: improved integration
+- General
+    - Fixed visual bug when matcaps are not installed. Light and Dark themes now use built-in matcaps
+    - Ray casts ignores source geometry that is clipped (near clip only) or culled (backface)
+    - Brush size (PolyStrips, Strokes, Relax, Smooth) is more consistent across screen
+    - Fixed many smaller bugs
+    - Restructured, refactored, and cleaned code base
+    - Auto saves will make a few attempts before alerting of failure
+
+### RetopoFlow 3.2.9&rarr;3.3.0
+
+- New undo system
+- New recovery system
+- Revamped action system
+- Added button to open online documents for Warning Details
+- Improved error handling at startup
+- Refactored large sections and cleaned code
+- Removed code for Blender 2.79 and earlier
+- Reorganized file structure
+- Improved Hive integration
+- Added option to keep viewport orbit center when nothing is selected
+- Added options to control Tweak/Relax brush alpha
+- Fixed disappearing text on detail UI elements at certain Blender UI scales
+- Fixed crash when exiting RetopoFlow after starting in wireframe mode
+- Fixed issue where selected but hidden geometry could get deleted
+- Turning off shading optimization now restores original shading settings
+- General code improvement
+
+### RetopoFlow 3.2.8&rarr;3.2.9
+
+- Fixed bug where scaling of target and viewport changes with save/undo
+- Fixed rare bug in PolyPen
+
+### RetopoFlow 3.2.7&rarr;3.2.8
+
+- Fixed bug where checkedness of alert checkboxes is not saved
+- Fixed bug with Stroke snapping distance
+
+### RetopoFlow 3.2.6&rarr;3.2.7
+
+- Fixed bug when pressing MMB while moving geometry with LMB
+- Significantly improved Auto Save and Auto Save recovery
+- Added quick bail if unexpected exceptions occur to prevent work loss
+- Temp mesh is used when updating to prevent work loss
+- PolyPen now has option to adjust distance for inserting vertex into edge
+- Fixed issue where loose verts and edges are unselectable
+- Fixed issue with crashing when using tablet
+- Improved auto adjustment of view clipping
+- Improved stability of Strokes and PolyPen
+- Added option for snapping to geometry while using Strokes instead of using brush radius
+- Checking for invalid characters in add-on folder name
+- Improved and debugged UI code
+- Removed RetopoFlow menu from all modes other than Object and Mesh Edit
+- Moved version number from the menu title to the menu header
+
+### RetopoFlow 3.2.5&rarr;3.2.6
+
+- Vertex pinning and unpinning, where pinned vertices cannot be moved
+- Seam edges can be pinned
+- Option to hide mouse cursor when moving geometry
+- Keymap editor improvements: shows keys for done and toggle UI, added Blender passthrough, fixed many bugs
+- Fixed bug where modifier key states would be out of sync if pressed or unpressed while changing view
+- Added auto clip adjustment setting, which adjusts clip settings based on view position and distance to bbox of sources
+- Fixed visualization bug where depth test wasn't always enabled and depth range might not be [0,1]
+- Added check for and button to select vertices that are on the "wrong" side of symmetry planes.
+- Fixed many bugs and cleaned up code
+
+### RetopoFlow 3.2.4&rarr;3.2.5
+
+- Worked around a major crashing bug in Blender 3.0 and 3.1
+- Overhauled RetopoFlow's Blender menu, by adding custom icons to buttons, improving the wording, buttons to online help documents, buttons to updater
+- Modifier keys (i.e., `Ctrl`, `Shift`, `Alt`, `OSKey`) now show OSX-specific symbols (i.e., `^`, `⇧`, `⌥`, `⌘`) for better readability on OSX machines
+- Improved keymap editor
+- Minor improvements for smaller screens
+- Started working on improvements for error reporting
+- Started refactoring code for major changes to Blender 3.0+ API, such as removing dependence on the deprecated `bgl` module
+- Many bug fixes
+- General cleaning up of old code and adding comments
+
+### RetopoFlow 3.2.3&rarr;3.2.4
+
+- Fixed visual bug that affected machines with Apple's M1 processor (issue #915)
+
+### RetopoFlow 3.2.2&rarr;3.2.3
+
+- Worked around a bug with Apple M1 MacBook Pro / Intel graphics card where Blender would crash on load
+- Warn if a source or the target has non-invertible transformation matrix
+- Minor change due to Blender 3.0 deprecating `blf.KERNING_DEFAULT`
+
+### RetopoFlow 3.2.1&rarr;3.2.2
+
+- Fixed major updater bug
+- Fixed bug where Brush Falloff with `Ctrl+F` was not working
+
+### RetopoFlow 3.2.0&rarr;3.2.1
+
+- Fixed issue where normals are not computed correctly after applying symmetry
+- Added shortcuts to increase and decrease brush radius for Tweak and Relax
+- Fixed scrolling UI with trackpad
+- Minor fixes across several tools (Contours, PolyStrips, Loops, Strokes, Relax, Tweak)
+- Broad and general maintenance (code refactoring, cleaning, and commenting)
+- Minor UI/UX improvements
+
+### RetopoFlow 3.1.0&rarr;3.2.0
+
+- Added builtin Keymap Editor (prototype)
+- Significantly improved performance of tools with large target meshes!
+- Target mesh visualization will now split (under the hood) when working on a small portion, improving feedback performance for some actions
+- Shortest path selection keymap default changed from `Shift+Alt+LMB/RMB+Double` to `Ctrl+Shift+LMB/RMB+Click` to better match Blender
+- Added ability to hide/reveal target mesh geometry
+- Added button to recalculate normals in the Target Cleaning panel
+- Added ability to Collapse Edges & Faces from delete/dissolve/collapse menu
+- Tweak and Relax can now slide vertices along a boundary
+- New Plane Symmetry Visualization setting, which is now default for better performance
+- Added selection options to help with selecting hard-to-get vertices
+- Improved Updater System
+- General code cleanup and refactoring
+- Works in Blender 2.83.0--3.0.0alpha (as of 2021.06.21)
+- Many bug fixes and UX improvements
+
+### RetopoFlow 3.00.2&rarr;3.1.0
+
+- Knife is a new tool for cutting into existing geometry!
+- Selection painting now selects geometry along shortest path from where mouse was first pressed to the geometry nearest current mouse position
+- Tools are much more responsive when working on targets with high geometry counts
+- Loops, Tweak, and Relax now have quick shortcuts
+- The tools pie menu is now `Q` as well as `~` to help reduce finger gymnastics
+- Major UI performance improvements from redesign and reimplementation of underlying UI system
+- Improved smart selection and added actions for selecting geometry along shortest path
+- Added button to push target vertices along normal before snapping to fix vertices snapping to inner source surfaces
+- Added updater system for updating to specific branches or commits
+- Added actions for hiding or revealing target geometry
+- Added button on help system to view help documents in web browser and to open FAQ
+- Added Blender operator for creating new target mesh based on active source mesh
+- Visualizing non-manifold edges and detached vertices
+- Many bug fixes and UX improvements
+
+### RetopoFlow 3.00.1&rarr;3.00.2
+
+- Tweak/Relax: added brush presets
+- Symmetry: added button to apply symmetry, improved visualization
+- PolyStrips/Strokes: brush settings now remain through sessions
+- Strokes: added span insert modes (fixed, brush size) and brush size adjustment
+- Improved ability to select geometry
+- Added edge flow smooth feature
+- Several bug fixes and UX improvements
+
+### RetopoFlow 3.00.0&rarr;3.00.1
+
+- PolyPen: added ability to move edge with drag after inserting new quad (before releasing insert)
+- Strokes: added a simple visualization to show how a stroke will connect to hovered existing geometry.  Still a work-in-progress!
+- Dissolving edges now dissolves verts (similar to Blender)
+- Tweak/Relax: brushes now do not become fully opaque (nor fully transparent) when strength is set to 1 (or 0)
+- Patches: improved code to detect good candidates for bridging two I-strips
+- PolyPen: PP-specific pie menu now shown in help doc
+- Added quit confirmation dialog when using {{done}}.  This dialog can be disabled.
+- Added Delete/Dissolve pie menu using {{delete pie menu}}
+- Other miscellaneous bug fixes
+
+### RetopoFlow 2.x&rarr;3.00.0
+
+- Left-mouse select is now a thing!
+- Mouse dragging, clicking, and double-clicking are now possible actions.
+- Some of the keymaps for some tools have changed to allow for LMB-select.
+- The target mesh is what you are currently editing (Edit Mode), and the source meshes are any other visible mesh.
+- RF now automatically detects many common mesh errors, such as vertices with invalid coordinates and inward-facing normals.
+- Some RF tools have improved options.
+- Major UI and UX improvements, including: tooltips, labels, help docs, gizmo rendering, minimizing main tool window
+- Improved consistency across all tools
+- Tools refresh faster when in middle of editing
+- Code optimization, cleanup, and refactoring
+- Reworked Auto Save and Save to be more intuitive and handle errors better
+- Works in Blender 2.8x and 2.9x
+- Fixed many issues
+
+## Blender versions
+
+As of the time of this release, RetopoFlow has been tested to work well with Blender&nbsp;2.83&nbsp;(LTS)--2.92α.
+
+Note: This version of RetopoFlow will *not* work in Blender&nbsp;2.79b or earlier.
+
+## Version 2.x&rarr;3.x Notes
+
+In RetopoFlow&nbsp;2.x, we completely rewrote the framework so that RF acts like any other Blender mode (like Edit Mode, Sculpt Mode, Vertex Paint Mode).
+Choosing one of the tools from the RetopoFlow panel will start RetopoFlow Mode with the chosen tool selected.
+
+Although the underlying framework has changed significantly, RetopoFlow&nbsp;3.x uses a similar workflow to RetopoFlow&nbsp;2.x.
+
+When RetopoFlow Mode is enabled, all parts of Blender outside the 3D view will be darkened (and disabled) and windows will be added to the 3D view.
+These windows allow you to switch between RF tools, set tool options, and get more information.
+Also, this one-time Welcome message will greet you.
+
+## New Framework
+
+Due to some significant changes in the Blender&nbsp;2.80 Python API, we had to rewrite a few key parts of RetopoFlow, specifically the rendering and UI.
+Rather than keeping these updates only for RetopoFlow users, we decided to build the changes into a new framework called [CookieCutter](https://github.com/CGCookie/addon_common).
+The CookieCutter framework has several brand new systems to handle states, UI drawing and interaction, debugging and exceptions, rendering, and much more.
+CookieCutter was built from the ground up to be a maintainable, extensible, and configurable framework for Blender add-ons.
+
+The new RetopoFlow sits on top of the CookieCutter framework, and we are excited to show off CookieCutter's features through RetopoFlow!
+
+But with any unveiling on new things, there are new bugs and performance issues.
+Our hope is that these problems will be much easier to fix in the new CookieCutter framework.
+We will need your help, though.
+If you notice a bug, please report it on the [Blender Market](https://blendermarket.com/products/retopoflow) or on [GitHub](https://github.com/CGCookie/retopoflow/issues).
@@ -0,0 +1,56 @@
+# ![](images/contours-icon.png) Contours Help
+
+Shortcut: {{contours tool}}
+
+The Contours tool gives you a quick and easy way to retopologize cylindrical forms.
+For example, it's ideal for organic forms, such as arms, legs, tentacles, tails, horns, etc.
+
+The tool works by drawing strokes perpendicular to the form to define the contour of the shape.
+Each additional stroke drawn will either extrude the current selection or cut a new loop into the edges drawn over.
+
+You may draw strokes in any order, from any direction.
+
+![](images/help_contours.png)
+
+
+## Creating
+
+|  |  |  |
+| --- | --- | --- |
+| {{insert}}                           | : | draw contour stroke perpendicular to form. newly created contour extends selection if applicable. |
+| {{increase count}}                   | : | increase segment counts in selected loop |
+| {{decrease count}}                   | : | decrease segment counts in selected loop |
+| {{fill}}                             | : | bridge selected edge loops |
+
+
+## Selecting
+
+|  |  |  |
+| --- | --- | --- |
+| {{select single, select single add}} | : | select edge |
+| {{select smart, select smart add}}   | : | smart select loop |
+| {{select paint, select paint add}}   | : | paint edge selection |
+| {{select path add}}                  | : | select edges along shortest path |
+| {{select all}}                       | : | select / deselect all |
+| {{deselect all}}                     | : | deselect all |
+
+## Transforming
+
+|  |  |  |
+| --- | --- | --- |
+| {{action}}           | : | grab and slide selected geometry under mouse |
+| {{grab}}             | : | slide selected loop |
+| {{rotate plane}}     | : | rotate selected loop in plane |
+| {{rotate screen}}    | : | rotate selected loop in screen |
+| {{smooth edge flow}} | : | smooths edge flow of selected geometry |
+
+## Other
+
+|  |  |  |
+| --- | --- | --- |
+| {{delete}}         | : | delete/dissolve/collapse selected |
+
+## Tips
+
+- Extrude Contours from an existing edge loop by selecting it first.
+- Contours works with symmetry, enabling you to contour torsos and other symmetrical objects!
@@ -0,0 +1,99 @@
+# RetopoFlow Debugging
+
+If you run into an issue while using RetopoFlow, you can report it via [Product Support](https://blendermarket.com/products/retopoflow) on Blender Market or by creating an issue via GitHub RetopoFlow [Issues](https://github.com/CGCookie/retopoflow/issues/new/choose).
+These RetopoFlow issues covers bugs within RetopoFlow or unexpected behavior of tools.
+
+Note: support via GitHub will be limited to fixing RetopoFlow bugs.
+The Blender Market route will provide you premium support.
+
+Whichever path of support you take, there are a few things to keep in mind to help us in debugging and fixing the issue as quickly as possible.
+The list below contain a few of these.
+
+- Explain clearly the context.  For example, add a screenshot or share a .blend file that shows what the scene looked like before you had the issue, what action you did to cause the issue, and what was the result of the action.
+
+- Consider sharing your .blend file with us.  Often times, the .blend file has a particular setting that we have not tested, and having access to your file will make reproducing your issue easier.
+
+- Try to reproduce the issue on the default Blender scene, or try to reproduce the issue on another machine, especially a different system (OSX, Windows, Linux) if possible.
+
+- Be sure to include all of the terminal / console output in your post (see below).
+
+- Be sure to include the machine information, Blender version, and RetopoFlow version in your post.
+
+- Be sure to reply to our questions.  If we are unable to reproduce the issue, and it goes without any activity for a time, we will close the issue.
+
+
+## Terminal / Console Output
+
+Sometimes an issue is caused by a different part of code than what is reported.
+By design, we do not report all the information in RetopoFlow, but that information might be critical to solving the issue.
+You can access the additional information through the system terminal / console.
+
+Note: There might be a lot of info in there (have to scroll), so be sure to copy _all_ of the text from the terminal / console.
+
+
+### Built-in Deep Debugging
+
+This simplest way to report the terminal output is to enable Deep Debugging.
+
+Note: you will need to restart Blender after enabling.
+
+![](images/debugging_enable.png max-height:200px)
+
+
+When Deep Debugging is enabled, all terminal output will be redirected to a text file.
+
+- Start Blender, enabled Deep Debugging, restart Blender
+- Start RetopoFlow
+- Once issue occurs, exit RetopoFlow
+- Under the RetopoFlow menu, choose Open Debugging Info
+
+![](images/debugging_open.png max-height:200px)
+
+
+### Windows
+
+- Start Blender as usual
+- In the Blender Menu: Windows > Toggle System Console.  The system console window will now open; minimize for now.
+- Start RetopoFlow
+- Once issue occurs, switch to the system console.
+
+### OSX
+
+Option 1:
+
+- Right click on Blender app (ex: in Applications), then click New Terminal at Folder.  The system terminal window will now open.
+- In the terminal, type `./Contents/MacOS/Blender` to start Blender.
+- Start RetopoFlow
+- Once issue occurs, switch to the system terminal.
+
+Option 2:
+
+- Open Terminal (Command+Space, type Terminal)
+- Open Finder, and browse to the Blender app.
+- Right click on Blender, then click Show Package Contents.
+- Open Contents folder, then open MacOS folder
+- Drag the blender file to the Terminal window
+- In Terminal, press enter.
+- Start RetopoFlow
+- Once issue occurs, switch to the system terminal.
+
+### Linux
+
+Option 1:
+
+- Right click Blender app
+- Choose Edit Application
+- Under Advanced tab, check "Run in terminal"
+- Save and close
+- Start Blender as normal, but now a terminal window will show right before Blender loads.
+- Start RetopoFlow
+- Once issue occurs, switch to the system terminal.
+
+Option 2:
+
+- Open system terminal / console
+- Type `/path/to/blender`, where `/path/to` is the path to the blender binary.
+  ex: `/home/username/Downloads/Blender\ 3.0.1/blender`
+  ex: `/usr/bin/blender`
+- Start RetopoFlow
+- Once issue occurs, switch to the system terminal / console
@@ -0,0 +1,37 @@
+# RetopoFlow FAQ
+
+Below are answers to some common questions with RetopoFlow.
+
+
+## Q: I cannot create new geometry!  Help!?
+
+All of the tools (except Patches, Tweak, and Relax) create geometry using {{insert}} action.
+Selection uses the {{select single}} action.
+See [General Help](general.md) for more actions.
+
+
+## Q: Why can I not select the geometry?
+
+If you have symmetry turned on, you can only select the geometry on the non-mirrored side of the model.
+Sometimes the geometry can snap to source surfaces that are "hidden" (see next Q).
+
+
+## Q: Why is my geometry below the source mesh?
+
+Sometimes when the source mesh contains objects that overlap (or nearly overlap), RetopoFlow will snap geometry to the inner surface.
+Use the "Push and Snap" operation under Options > Target Cleaning to push the vertices out along normal before snapping them back to the source surface.
+
+
+## Q: I have symmetry turned on, but why is it not working?
+
+RetopoFlow's symmetry follows Blender's symmetry model, where symmetry is based on the origin of the target object.
+In fact, enabling symmetry in RetopoFlow will add a Mirror Modifier to the target object in Blender.
+
+RetopoFlow will create the new target object similar to Blender---at the 3D Cursor---so make sure to position correctly the 3D Cursor before creating a new target mesh.
+If you have already started working on a target mesh, edit the origin as you would in Blender.
+
+
+## Q: How do I continue working on a previous target?
+
+To continue working on a target mesh, select the target, switch to Edit Mode, then choose one of the RetopoFlow tools from the RetopoFlow menu.
+
@@ -0,0 +1,165 @@
+# General Help
+
+Help Shortcut: {{general help}}
+
+When RetopoFlow Mode is enabled, certain shortcuts are available regardless of the tool selected.
+For tool-specific help, select the tool from the Tools panel, and either press {{tool help}} or click Tool Help.
+
+View the [table of contents](table_of_contents.md) for all built-in documentation by pressing {{all help}} at any time.
+
+Below is a brief description of some of the features in RetopoFlow.
+For more details, see the tooltips when hovering or the product documentation page.
+
+
+## RetopoFlow Shortcuts
+
+|  |  |  |
+| --- | --- | --- |
+| {{done,done alt0}} | : | quit RetopoFlow |
+| {{blender save}}   | : | save blend file (same as Blender's save) |
+| {{general help}}   | : | view general help (this document) |
+| {{all help}}       | : | view all help documents (table of contents) |
+| {{tool help}}      | : | view help for currently selected tool |
+| {{toggle ui}}      | : | toggle on/off main RF windows |
+
+## Tool Shortcuts
+
+Pressing the tool's shortcut will automatically switch to that tool.
+The shortcuts for each tool is a number at top of keyboard (not numpad numbers).
+
+|  |  |  |  |
+| --- | --- | --- | --- |
+| {{contours tool}}   | : | Contours   | [help](contours.md)   |
+| {{polystrips tool}} | : | PolyStrips | [help](polystrips.md) |
+| {{strokes tool}}    | : | Strokes    | [help](strokes.md)    |
+| {{patches tool}}    | : | Patches    | [help](patches.md)    |
+| {{polypen tool}}    | : | PolyPen    | [help](polypen.md)    |
+| {{knife tool}}      | : | Knife      | [help](knife.md)      |
+| {{loops tool}}      | : | Loops      | [help](loops.md)      |
+| {{tweak tool}}      | : | Tweak      | [help](tweak.md)      |
+| {{relax tool}}      | : | Relax      | [help](relax.md)      |
+| {{select tool}}     | : | Select     | [help](select.md)     |
+
+Note: selection and the undo stack is maintained between tools.
+
+![Pie menu](images/pie_menu.png max-height:240px)
+
+Press {{pie menu}} at any time to show the tool pie menu.
+
+
+## Quick Tool Shortcuts
+
+Pressing the tool's quick shortcut will temporarily switch to that tool.
+RetopoFlow will switch back to the previously selected tool once you are done.
+
+|  |  |  |
+| --- | --- | --- |
+| {{loops quick}}  | : | Loops |
+| {{knife quick}}  | : | Knife |
+| {{tweak quick}}  | : | Tweak |
+| {{relax quick}}  | : | Relax |
+| {{select quick}} | : | Select |
+
+
+## Universal Shortcuts
+
+The following shortcuts work across all the tools, although each tool may have a distinct way of performing the action.
+For example, pressing `G` in Contours will slide the selected loop.
+
+|  |  |  |
+| --- | --- | --- |
+| {{insert}}                                     | : | create new geometry with current tool / apply relax or tweak |
+| {{select single, select single add}}           | : | select single |
+| {{select paint, select paint add}}             | : | selection painting when mouse hovers geometry |
+| {{select box}}                                 | : | box select when mouse does not hover geometry |
+| {{select smart, select smart add}}             | : | smart selection |
+| {{select path add}}                            | : | select along shortest path |
+| {{select all}}                                 | : | select / deselect all |
+| {{deselect all}}                               | : | deselect all |
+| {{select invert}}                              | : | invert selection |
+| {{select linked}}                              | : | select all linked |
+| {{select linked mouse, deselect linked mouse}} | : | select / deselect all linked under mouse |
+| {{hide selected}}                              | : | hide selected geometry |
+| {{hide unselected}}                            | : | hide unselected geometry |
+| {{reveal hidden}}                              | : | reveal hidden geometry |
+| {{action}}                                     | : | transform selection when mouse hovers selected geometry |
+| {{grab}}                                       | : | grab and move selected geometry |
+| {{rotate}}                                     | : | rotate selected geometry |
+| {{scale}}                                      | : | scale selected geometry |
+| {{rip}}                                        | : | rip selected edge |
+| {{rip fill}}                                   | : | rip and fill selected edge |
+| {{smooth edge flow}}                           | : | smooths edge flow of selected geometry |
+| {{delete}}                                     | : | delete / dissolve dialog |
+| {{delete pie menu}}                            | : | delete / dissolve pie menu
+| {{blender undo}}                               | : | undo |
+| {{blender redo}}                               | : | redo |
+| {{pin}}                                        | : | pin selected geometry |
+| {{unpin}}                                      | : | unpin selected geometry |
+| {{unpin all}}                                  | : | unpin all pinned geometry |
+| {{mark seam}}                                  | : | mark selected edges as seam |
+| {{clear seam}}                                | : | unmark selected edges as seam |
+
+
+General selection has a few options to help with selecting troublesome vertices (ex: just below surface of source).
+When `Occlusion Test` is enabled, geometry that is occluded by the source(s) are not selectable.
+When `Backface Test` is enabled, geometry that is facing away are not selectable.
+Disable these options to make geometry easier to select.
+
+![Selection options](images/selection_options.png max-height:250px)
+
+
+
+
+Pressing {{delete}} will bring up the Delete/Dissolve/Collapse dialog, allowing you to delete/dissolve/collapse the selected geometry.
+Pressing and holding {{delete pie menu}} will bring up a Delete/Dissolve pie menu, which has fewer options than the dialog but is generally faster.
+
+
+![Delete dialog and pie menu](images/delete_dialog_pie.png max-height:250px)
+
+
+
+## General Options
+
+The UI Scale option controls how large or small RetopoFlow will draw things.
+Larger numbers produce larger fonts, thicker lines, larger vertices, etc.
+
+If the Auto Hide Tool Options is checked, the options for the currently selected tool will be shown, but all other tool options will be hidden.
+
+<!-- The Maximize Area button will make the 3D view take up the entire Blender window, similar to pressing `Ctrl+Up` / `Shift+Space` / `Alt+F10`. -->
+
+
+
+
+### Target Cleaning
+
+The Snap Verts buttons will snap either All vertices or only Selected vertices to the nearest point on the source meshes.
+
+The Merge by Distance will merge vertices into a single vertex if they are within a given distance.
+
+
+
+
+### View Options
+
+The Clipping options control the near and far clipping planes.
+
+The Theme option changes the color of selected geometry.
+
+![](images/help_themes.png max-height:100px)
+
+The Target Drawing options control the rendering of the target mesh.
+The Above and Below options control transparency of the target mesh.
+Vertex Size and Edge Size control how large the vertices and how thick the edges are.
+
+
+
+
+
+
+## Mirror Options
+
+The X, Y, Z checkboxes turn on/off mirroring along the X, Y, Z axes.
+Note: these options utilize the mirror modifier.
+
+When mirroring is turned on, the mirroring planes can be visualized directly using Plane option, or indirectly by coloring the sources choosing either the Edge or Face option.
+The Effect setting controls the strength of the visualization.
@@ -0,0 +1,103 @@
+# Intro
+
+RetopoFlow is a suite of fun, sketch-based retopology tools for Blender from [Orange Turbine](https://orangeturbine.com) 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](https://orangeturbine.com/downloads/retopoflow) or the [Blender Market](https://blendermarket.com/products/retopoflow/).
+
+![Blender Market](images/blendermarket_screenshot.png)
+
+If you’re brand new to RetopoFlow, check the [Quick Start page](https://docs.retopoflow.com/quick_start.html).
+Otherwise, jump right over to the [Table of Contents](https://docs.retopoflow.com/table_of_contents.html).
+
+
+## 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](https://github.com/CGCookie/retopoflow), especially for students, teachers, and those using RetopoFlow for educational purposes.
+
+You may download RetopoFlow from your [account dashboard](https://blendermarket.com/account/orders) on the Blender Market once you have already purchased it or from RetopoFlow's [GitHub Releases Page](https://github.com/CGCookie/retopoflow/releases).
+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](https://www.gnu.org/licenses/gpl-3.0.en.html) 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`.
+
+![Installing RetopoFlow](images/install.png)
+
+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](https://docs.retopoflow.com/addon_updater.html) for more details.
+
+
+## Getting Support
+
+Here are ways to get help with a problem or a question that the [documentation](https://docs.retopoflow.com) isn't answering:
+
+- Get high priority support from Orange Turbine by sending a message from your [Blender Market inbox](https://blendermarket.com/inbox) once you've purchased a copy.
+- Create a new [issue](https://github.com/CGCookie/retopoflow/issues/new/choose) on RetopoFlow's [GitHub page](https://github.com/CGCookie/retopoflow).
+- Reach out to us via email at [retopoflow@cgcookie.com](mailto:retopoflow@cgcookie.com).
+
+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](https://docs.retopoflow.com/debugging.html) 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](https://github.com/CGCookie/retopoflow/issues) for the current to-dos.
@@ -0,0 +1,40 @@
+**PLEASE READ THE FOLLOWING AND USE THE TEMPLATE TO POST YOUR ISSUE**
+
+*Questions not directly related to the RetopoFlow project are considered general and should be posted elsewhere (e.g. git, blender, python, etc).*
+
+**Before raising the issue, please check the following first:**
+
+- [ ] Read through the README.md file in the branch used to assure the process taken is correct
+- [ ] Check the existing [issues](https://github.com/CGCookie/retopoflow/issues) and [pull requests](https://github.com/CGCookie/retopoflow/pulls) to make sure the issue has not already been reported and/or fixed.
+- [ ] You can replicate the bug and will provide as much info as possible with blend files, screenshots, logfiles, as well as show the expected result and actual result.
+
+Please prefix your issue name with one of the following: **[BUG]** **[PROPOSAL]** **[QUESTION]**
+
+
+Issue Template
+-----------------------------------
+
+RetopoFlow Version: {*add here*}
+
+Blender Version/Hash: {*add here*}
+
+Platform Version/Distribution: {*add here*}
+
+
+**Issue:**
+
+{*enter your issue here*}
+
+{*add any screenshots of the issue here*}
+
+
+**How to Reproduce:**
+
+- {*add your list replication steps*}
+
+{*attach any files needed to replicate the issue*}
+
+
+
+Automatically Generated Info
+-----------------------------------
@@ -0,0 +1,33 @@
+**PLEASE READ THE FOLLOWING AND USE THE TEMPLATE TO POST YOUR ISSUE**
+
+*Questions not directly related to the RetopoFlow project are considered general and should be posted elsewhere (e.g. git, blender, python, etc).*
+
+**Before raising the issue, please check the following first:**
+
+- [ ] Read through the README.md file in the branch used to assure the process taken is correct
+- [ ] Check the existing [issues](https://github.com/CGCookie/retopoflow/issues) and [pull requests](https://github.com/CGCookie/retopoflow/pulls) to make sure the issue has not already been reported and/or fixed.
+- [ ] You can replicate the bug and will provide as much info as possible with blend files, screenshots, logfiles, as well as show the expected result and actual result.
+
+Please prefix your issue name with one of the following: **[BUG]** **[PROPOSAL]** **[QUESTION]**
+
+
+Issue Template
+-----------------------------------
+
+**Issue:**
+
+{*enter your issue here*}
+
+{*add any screenshots of the issue here*}
+
+
+**How to Reproduce:**
+
+- {*add your list replication steps*}
+
+{*attach any files needed to replicate the issue*}
+
+
+
+Automatically Generated Info
+-----------------------------------
@@ -0,0 +1,25 @@
+# RetopoFlow Keymap Editor
+
+RetopoFlow has a very basic keymap editor to allow some customization of interaction.
+
+Start the editor by clicking the Keymap button in the Config section of the RetopoFlow Blender menu.
+
+![](images/keymap_button.png max-height:150px)
+
+IMPORTANT: This editor is an early prototype, and not all keymap settings will work as expected.
+
+Navigate the action categories to find lists of actions, each with a set of interactions that can be customized.
+
+- Click on the big button with interactions as text (example: Ctrl+LMB) will edit that specific interaction for the RetopoFlow action.
+- Click on the button with a `✕` to delete that interaction.
+- Click the `+ Add New Keymap` to add a new interaction for the action.
+- Click the `Reset Keymap` button to reset that action's keymaps to the default interactions.
+- Click the `Reset All` button at the bottom to reset _all_ of the custom keymaps back to their default interactions.
+
+![](images/keymap_all.png max-height:400px)
+
+When editing an interaction, a window will display with all the ways to map an interaction to the action.
+
+![](images/keymap_insert.png max-height:300px)
+
+
--- a/Show More
+++ b/Show More