Quick Start Guide

1. Install & Activate

   • Install the .rbz via Window → Extension Manager, then restart SketchUp.
   • Click the LoopCut toolbar icon, or use Plugins → LoopCut → Insert Loop Edge.
   • Default shortcut: Ctrl+R (changeable in Settings).

2. Make a Loop Cut

   • Hover over an edge. A preview of the loop/ring appears.
   • Click once to lock direction and enter slide mode.
   • Move the mouse to slide. Click to insert. Press Esc to cancel.

3. Switch Modes

   • Press TAB to open the mode dialog.
   • Topology: best for quad meshes, QuadFace-style diagonals, and edge rings.
   • Geometric: best for triangulated, ngon, terrain, or mixed meshes.

4. Modifier Keys

   • Shift: Topology = toggle straight/tilted direction; Geometric = force vertical plane.
   • Ctrl: Geometric = force horizontal plane.
   • Alt: separate mode (Alt+Click to separate into two groups).

5. VCB Commands

   • 50 → 50%
   • 25mm → distance from edge
   • 30% → relative position
   • X5 → insert 5 evenly spaced loops (max 30)

6. Separate

   • Hold Alt and click. The smaller side becomes a new group named "LoopCut_Piece".

7. Tips

   • Inside a Group/Component: double-click to enter its editing context first.
   • If the cut fails, press TAB and try the other mode.
   • Use the VCB for precise placement; press Enter to confirm.

Quick Start: 1. Plugins → LoopCut → Insert Loop Edge (Ctrl+R). 2. Hover an edge, click to start sliding. 3. Move mouse, click to insert; Esc to cancel. 4. TAB = switch Topology/Geometric. 5. Shift/Ctrl = force direction/plane; Alt+Click = separate. 6. VCB: 50, 25mm, 30%, X5.

LoopCut — Main Documentation Version 1.1.0 Compatible with SketchUp 2017+ (SketchUp 2021+ recommended for shortcut registration)

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

1. OVERVIEW

LoopCut brings a Blender/Maya-style loop-cut workflow to SketchUp. Select an edge, move the mouse to slide, preview the cut live, and click to insert. It supports both quad-based topology and arbitrary meshes.

Unlike SketchUp's built-in Divide or Offset tools, LoopCut inserts a complete edge ring (Topology Mode) or a plane-cut loop (Geometric Mode), and respects quad topology, triangulated meshes, and QuadFace-style soft+smooth diagonals.

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

2. FEATURES

• Two cutting modes: - Topology Mode: edge-ring based, best for quad meshes. - Geometric Mode: plane-face intersection, best for triangulated, ngon, terrain, or mixed meshes.

• Live preview with throttled refresh for smooth performance.

• VCB input: - Percentage: 50 - Distance with unit: 25mm, 3cm, 0.2m - Relative: 30% - Batch: X5 inserts 5 evenly spaced loops (max 30).

• ALT+Click separation: - Splits the mesh along the cut line into two groups. - The smaller side becomes a group named "LoopCut_Piece".

• UV and material inheritance: - Front/back materials are captured and restored. - Front/back UVs are restored to the nearest vertex.

• QuadFace diagonal support: - Detects soft+smooth diagonals used by QuadFace Tools, Artisan, SubD, and similar workflows. - Temporarily unsplits and re-flags them after cutting.

• Nested Group / Component awareness: - Works inside groups and component instances. - Handles world/local coordinate transforms correctly.

• Multi-language UI: - English, 简体中文, 日本語.

• Settings dialog: - Language, default mode, preview throttle, BFS max faces, debug mode, keyboard shortcut.

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

3. INSTALLATION

Method A — Extension Manager (recommended) 1. Download LoopCut_v1.0.0.rbz. 2. In SketchUp: Window → Extension Manager → Install Extension. 3. Select the .rbz file and confirm. 4. Restart SketchUp.

Method B — Manual (for developers) 1. Place the "LoopCut" folder into your SketchUp Plugins directory: Windows: %AppData%\SketchUp\SketchUp 20XX\SketchUp\Plugins macOS: ~/Library/Application Support/SketchUp 20XX/SketchUp/Plugins 2. Restart SketchUp.

After installation, activate LoopCut from: • Toolbar: LoopCut icon • Menu: Plugins → LoopCut → Insert Loop Edge • Shortcut: Ctrl+R (default, configurable in Settings)

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

4. QUICK START

1. Activate the tool.
2. Hover over an edge. A preview appears.
3. Click once to lock direction and enter slide mode.
4. Move the mouse to adjust position.
5. Click to insert. Press Esc to cancel.
6. Press TAB to switch between Topology and Geometric modes.
7. Hold ALT and click to separate into two groups.
8. Use VCB for precise input or X5 for batch insert.

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

5. INTERFACE & STATES

The tool has two main states:

• IDLE - Hover an edge to preview the cut. - Click an edge to enter SLIDING state.

• SLIDING - Move the mouse to adjust the cut position. - Click to confirm and insert. - Press Esc to cancel. - Type in VCB for precise input.

The status bar shows: • Current mode • Current percentage • Distance from the nearest edge • Separate mode hint when ALT is held

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

6. CUTTING MODES

6.1 TOPOLOGY MODE

Best for: • Quad meshes • QuadFace-style soft+smooth diagonals • Clean edge rings • Subdivision-style modeling

How it works: • Traverses the edge ring using quad opposite-edge relationships. • Uses multi-relay traversal for open or partial rings. • Detects QuadFace diagonals and treats them as virtual quads. • Handles triangulated terrain: - If a ring touches only one edge of a triangle, a cut is drawn from the split point to the opposite vertex. • Handles vertex junctions: - If a face has 3 or more ring edges, the longest cut across the face is used. • Uniform direction: - Shift toggles between straight and tilted direction. - Helps avoid flipped insertions on opposite edges.

6.2 GEOMETRIC MODE

Best for: • Triangulated meshes • Ngons • Terrain • Mixed topology • Non-quad surfaces

How it works: • Builds a cutting plane from the selected edge and offset ratio. • Intersects that plane with all related faces. • Uses bounded BFS to find related faces. • Smart extreme-position handling: - At 0% or 100%, it uses a 1% / 99% reference shape and shifts it to the target position. - Prevents degenerate zero-length cuts. • Force plane orientation: - Shift: force vertical plane. - Ctrl: force horizontal plane.

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

7. CONTROLS & MODIFIERS

TAB Switch between Topology Mode and Geometric Mode.

Shift Topology Mode: toggle straight / tilted direction. Geometric Mode: force vertical plane.

Ctrl Geometric Mode: force horizontal plane.

ALT Separate mode. Hold ALT and click to separate into two groups.

ESC Cancel current slide, or exit the tool when idle.

VCB X{n} Batch insert n loops. Example: X5 inserts 5 loops. Maximum: 30.

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

8. VCB INPUT

The VCB accepts:

• Percentage: 50 → 50%

• Relative percentage: 30% → 30%

• Distance with unit: 25mm → 25 millimeters 3cm → 3 centimeters 0.2m → 0.2 meters

• Plain number: 0–100 → treated as percentage Other → treated as a distance based on the model unit

• Batch: X5 → insert 5 evenly spaced loops

Press Enter to confirm the VCB value.

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

9. BATCH INSERT

Type X{n} in VCB to insert n loops at once. The ring is divided into n+1 segments.

Examples: • X1 → 2 segments • X5 → 6 segments • X10 → 11 segments

Limits: • Minimum: 1 • Maximum: 30

Batch insert works in both Topology and Geometric modes. If some steps fail, the tool reports how many succeeded.

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

10. SEPARATE (ALT+CLICK)

Hold ALT and click to separate the mesh along the cut line.

How it works: • Inserts the cut loop. • Collects the connected component of the start edge. • Flood-fills from the cut line's seed face. • Never crosses cut edges or open boundaries. • Chooses the smaller side as the new group. • Names the group "LoopCut_Piece".

Notes: • Works best on manifold meshes. • Non-manifold geometry may cause separation to fail. • Only the connected component of the selected edge is processed.

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

11. UV & MATERIAL INHERITANCE

Before cutting: • Front material is captured. • Back material is captured. • Front UVs are captured per vertex. • Back UVs are captured per vertex.

After cutting: • Materials are restored to affected faces. • UVs are restored to the nearest original vertex. • Tolerance: 0.01 inch.

Notes: • Highly distorted UVs may need manual remapping. • QuadFace diagonals are restored as soft+smooth after cutting.

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

12. GROUPS & COMPONENTS

LoopCut works inside groups and component instances.

Important: • Double-click to enter the group/component editing context first. • The tool uses SketchUp's active_path to determine the correct editing context. • World/local coordinate transforms are handled automatically. • Nested transformations are composed and inverted correctly.

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

13. SETTINGS

Open: Plugins → LoopCut → Settings...

Available settings: • Language: English / 简体中文 / 日本語 • Default mode: Topology / Geometric • Preview refresh throttle (ms) • Max BFS faces • Debug mode • Keyboard shortcut

Notes: • Language and shortcut changes may require a SketchUp restart. • Settings are saved via Sketchup.write_default.

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

14. TROUBLESHOOTING

Problem: Insert fails. Solution: • Press TAB and try the other mode. • Try another edge. • Check for non-manifold geometry, open boundaries, or topology gaps.

Problem: Cut is only partial. Solution: • LoopCut stops at non-manifold edges, boundaries, or topology gaps. • This is intentional to avoid invalid geometry. • Try Geometric Mode for mixed or triangulated meshes.

Problem: Batch insert fails on some steps. Solution: • Reduce the number of loops. • Simplify the mesh locally. • Try again in the other mode.

Problem: UVs look slightly off. Solution: • UV restoration uses nearest-vertex matching. • For highly distorted UVs, re-map manually after cutting.

Problem: Separation fails. Solution: • The mesh may be non-manifold. • Try a different cut line. • Make sure the selected edge is part of a connected component.

Problem: Shortcut does not work. Solution: • Shortcut registration requires SketchUp 2021+. • Restart SketchUp after changing the shortcut. • Check for conflicts with other extensions.

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

15. FAQ

Q: What is a QuadFace diagonal? A: A soft+smooth edge shared by two adjacent faces. Tools like QuadFace Tools, Artisan, and SubD use this convention to mark virtual quads inside triangulated meshes.

Q: Why does LoopCut stop at some edges? A: It stops at non-manifold edges, boundaries, or topology gaps to prevent invalid geometry.

Q: Can I use LoopCut on SketchUp Make? A: SketchUp Make does not support extensions. Use SketchUp Pro/Studio.

Q: Can I insert more than 30 loops? A: The batch limit is 30 for responsiveness. Run X30 multiple times if you need more.

Q: Does LoopCut work on curved surfaces? A: Yes, within the limits of the mesh topology. Geometric Mode is usually better for curved or triangulated surfaces.

Q: Does LoopCut preserve materials? A: Yes. Front and back materials are captured and restored.

Q: Does LoopCut preserve UVs? A: Yes, using nearest-vertex matching. Complex UV layouts may need manual adjustment.

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

16. VERSION HISTORY

v1.0.0 • Initial public release. • Topology Mode with edge-ring traversal and QuadFace support. • Geometric Mode with plane-face intersection and BFS. • Smart extreme-position handling for 0% / 100%. • Live preview with throttled refresh. • VCB input: %, mm/cm/m, relative distance. • Batch insert: X{n}. • ALT+Click separation. • UV and material inheritance. • Nested Group / Component coordinate awareness. • Multi-language UI: EN / ZH / JA. • Settings dialog with persisted defaults.

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

17. SUPPORT

For support, bug reports, and feature requests, please reply to the SketchUcation forum thread for LoopCut.

If this plugin helps your work, any small donation is appreciated for further development. More new features will be added in future updates.

© 2026 LoopCut xoabin

Changelog

v1.1.0 — 2026-09-28 Initial public release.

New Features: • Added Blender-style loop cut for SketchUp. • Added two cutting modes: - Topology Mode: edge-ring based, supports quad meshes and QuadFace-style soft+smooth diagonals. - Geometric Mode: plane-face intersection, supports triangulated, ngon, terrain, and mixed meshes. • Added live preview with throttled refresh. • Added VCB input: - Percentage: 50 - Relative percentage: 30% - Distance with unit: 25mm, 3cm, 0.2m - Batch insert: X5 inserts 5 evenly spaced loops (max 30). • Added ALT+Click separation along the cut line. • Added UV and front/back material inheritance. • Added QuadFace diagonal detection, splitting, and restoration. • Added nested Group / Component coordinate awareness. • Added multi-language UI: English, 简体中文, 日本語. • Added Settings dialog: - Language - Default mode - Preview refresh throttle - Max BFS faces - Debug mode - Keyboard shortcut (default Ctrl+R)

Improvements: • Smart extreme-position handling for 0% and 100% cuts. • Multi-relay traversal for open or partial edge rings. • Triangulated terrain handling in Topology Mode. • Vertex junction handling when a face has 3 or more ring edges. • Bounded BFS for Geometric Mode to avoid scanning the whole model. • Component-aware separation: only the connected component of the start edge is processed. • World/local coordinate transform support for nested groups and components.

Fixes: • Prevented degenerate zero-length cuts at extreme positions. • Prevented duplicate edge creation. • Restored soft+smooth flags on QuadFace diagonals after cutting. • Restored materials and UVs after cutting. • Improved handling of non-manifold geometry and open boundaries.

Notes: • Requires SketchUp 2017 or newer. • Shortcut key registration requires SketchUp 2021 or newer. • Language and shortcut changes may require a SketchUp restart.