SURFACE NAVIGATION (COMPLETE) - USER DOCUMENTATION

===========================================================

TABLE OF CONTENTS
1. Introduction
2. Installation
3. Basic Usage
4. Navigation Controls
5. Settings and Configuration
6. Advanced Features
7. Troubleshooting
8. Tips and Best Practices

===========================================================

1. INTRODUCTION

Surface Navigation is a powerful Blender addon that revolutionizes 3D viewport navigation by allowing you to orbit, zoom, and pan around actual surface points in your scene. Unlike standard navigation that uses arbitrary centers, this addon provides precise, surface-based control for enhanced modeling and sculpting workflows.

===========================================================

2. INSTALLATION

1. Download the addon file (view_rotation_addon.py)
2. Open Blender and go to Edit > Preferences > Add-ons
3. Click "Install..." button
4. Select the downloaded .py file
5. Enable the addon by checking the box next to "Surface Navigation (Complete)"
6. The addon is now ready to use

===========================================================

3. BASIC USAGE

The addon introduces three new navigation modes that work with the Alt key:

• Alt + Left Mouse Button = Orbit around surface
• Alt + Right Mouse Button = Zoom centered on surface  
• Alt + Middle Mouse Button = Pan based on surface

Simply hold Alt and click on any surface in your 3D scene to start navigating around that point.

===========================================================

4. NAVIGATION CONTROLS

ORBIT (Alt + Left Click)
- Click and drag on any surface to orbit around that point
- The view rotates around the exact surface location you clicked
- Release Alt to end the operation and maintain the new view
- Press Esc to cancel and return to original view

ZOOM (Alt + Right Click)
- Click on a surface and move mouse up/down to zoom
- Zoom is centered on the surface point you clicked
- Mouse movement controls zoom speed and direction
- Release Alt or Right Mouse to finish zooming
- Press Esc to cancel and restore original distance

PAN (Alt + Middle Click)
- Click on a surface to set a reference point
- Drag to pan the view while maintaining the surface reference
- The 3D cursor may move to show the reference point (configurable)
- Release Alt to end panning
- Press Esc to cancel the operation

===========================================================

5. SETTINGS AND CONFIGURATION

Access settings through the 3D Viewport sidebar (N panel) > Tool tab > Surface Navigation panel.

ZOOM SETTINGS:
• Zoom Sensitivity (0.001-0.1): Controls how fast zooming responds to mouse movement
• Minimum Zoom Distance: Prevents zooming too close to objects
• Maximum Zoom Distance: Sets the furthest zoom limit

OPERATION BEHAVIOR:
• Show Cursor During Operation: Displays 3D cursor at surface hit points
• Restore on Alt Release: Returns to original state when Alt is released

ADVANCED SETTINGS:
• Hit Detection Mode:
  - All Objects: Detect surfaces on all visible objects
  - Selected Objects: Only detect on selected objects
  - Visible Objects: Only detect objects in current layer

• Hit Point Update Threshold: Distance threshold for updating hit points (prevents jittery navigation)

RESET BUTTON:
Click "Reset Default Settings" to restore all settings to their original values.

===========================================================

6. ADVANCED FEATURES

HIT POINT THRESHOLD:
The threshold system prevents navigation from becoming jittery when moving the mouse slightly. If a new hit point is very close to the previous one, the addon continues using the previous point for smoother navigation.

CURSOR INTEGRATION:
When enabled, the 3D cursor moves to surface hit points during operations, providing visual feedback about where navigation is centered. The cursor automatically returns to its original position when operations end.

KEYMAP CUSTOMIZATION:
Advanced users can modify the key bindings in Blender's Keymap preferences if Alt+Mouse combinations conflict with other workflows.

===========================================================

7. TROUBLESHOOTING

ISSUE: Navigation doesn't work
SOLUTION: Ensure the addon is enabled and you're holding Alt while clicking on visible surfaces

ISSUE: No surface detection
SOLUTION: Check Hit Detection Mode settings - try "All Objects" mode for maximum detection

ISSUE: Zoom too fast/slow
SOLUTION: Adjust Zoom Sensitivity in settings panel

ISSUE: Navigation feels jittery
SOLUTION: Increase Hit Point Update Threshold value

ISSUE: Conflicts with other addons
SOLUTION: Check keymap settings and disable conflicting key bindings

ISSUE: Cursor doesn't return to original position
SOLUTION: Press Esc to cancel operation or disable "Show Cursor During Operation"

===========================================================

8. TIPS AND BEST PRACTICES

• Use different detection modes for different workflows:
  - "Selected Objects" for focused work on specific objects
  - "All Objects" for general scene navigation
  - "Visible Objects" when working with complex layered scenes

• Adjust zoom sensitivity based on your mouse and personal preference:
  - Lower values (0.001-0.005) for precise control
  - Higher values (0.01-0.05) for faster navigation

• Set appropriate zoom limits for your scene scale:
  - Smaller minimum distances for detailed work
  - Larger maximum distances for large scenes

• Use the cursor display feature to understand where navigation is centered

• Remember that releasing Alt maintains your current view, while Esc cancels and returns to the original view

• The addon works best with objects that have good surface detail for hit detection

• For sculpting workflows, consider using "Selected Objects" mode to focus navigation on your sculpt

===========================================================

SUPPORT AND FEEDBACK

For issues, suggestions, or feedback, please contact the addon developer. Regular updates ensure compatibility with new Blender versions and add requested features.

Version: 1.3.0
Compatible with: Blender 3.0+
Author: Han Yue + GPT

===========================================================
