Files
vectorcraft/docs/revolve.md
T
dotCooCoo 9e88bfe698 Revolve: a partial sweep with Cap closes its cut sides
With an Angle below 360 and Cap on, Revolve and Revolve (Classic) now
close the two angular cut sides instead of leaving them open. Each side
is flat and evenly shaded and is drawn in depth order with the rest of
the surface: the region between each open subpath and the axis, and the
area of each closed subpath, one face per region. A subpath that walls
a hole under the object's fill rule leaves the hole open, and a
self-intersecting subpath fills what the nonzero rule fills. The cut
sides appear in preview, SVG/PDF export, Expand Appearance, Expand as
Wireframes, shadows and exported 3D meshes. Cap off keeps the surface
hollow.

Painter visibility now looks for covers over every piece of a face, so
a face drawn as several contours is trimmed where any of them is
covered.

Docs: docs/revolve.md, docs/three-d.md, docs/mcp.md, the
effects-parity row, the Cap tooltip and its catalog rows.
2026-11-15 07:09:57 -08:00

132 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Revolve
This initial implementation follows the scope agreed in [issue #605](https://github.com/storytold/vectorcraft/issues/605#issuecomment-6070543567).
Select a path, compound path, type, clipping group, blend, symbol instance, or a group or layer of them, then choose **Effect > 3D and Materials > Revolve**.
On a group or layer, every visible member sweeps about one axis, as [the help page](https://helpx.adobe.com/illustrator/desktop/special-effects-styles/create-3d-graphics/create-3d-objects.html)
describes for a group. The following rules are VectorCraft's own: type stays editable and sweeps as its glyph outlines,
the shared axis lies on the chosen edge of the members' bounds together, and each member keeps its own paint.
The faces of all members draw in one back-to-front order. The opacity, blending mode and opacity mask of a member,
or of a group inside the group, apply once to all its faces. Where a face of another member lies between its faces
in that order and overlaps them on the page, its faces are split there, and the opacity, blending mode and opacity
mask apply once to each part. The mask stays where it is on the page; it does not turn with the faces.
Two faces overlap when the convex hulls of their outlines come within the 0.75 pt seam stroke of each other. After
4,194,304 overlap tests on one group, each further face of such a member is drawn as a part of its own.
The profile's horizontal distance from a vertical axis is its radius. **Axis side** chooses the left or right
edge of the profile's bounds; **Offset** moves the axis outward. For a cylinder made from a vertical
line, give it a nonzero offset. A vertical line at zero offset lies on the axis and has no surface.
**Revolve angle** sweeps 0 to 360 degrees. **Rotation X/Y/Z** rotates the viewing direction, with all three axes defaulting to 0 degrees. **Perspective**
runs 0° to 160°, as documented: 0° is an orthographic view, and wider angles bring the eye nearer (see
[three-d.md](three-d.md#perspective)). **Segments** controls radial resolution (8 to 128 for a full turn).
Lighting supports one to ten directional lights with the documented Light Settings (see [three-d.md](three-d.md#lighting)):
**Color**, **Intensity**, **Rotation**, **Height**, **Softness** and **Ambient Light**, and **Light behind the object**.
Color is white by default, with a picker and a reset dot. Colored light preserves neutral ambient illumination.
Turn **Shading** off to keep the source paint without lighting.
Shaded Revolve surfaces automatically use smooth lighting from the profile's tangents,
represented by linear gradients on vector triangles. There is no separate smoothing control.
Segments still controls the body silhouette; smoothing does not increase radial resolution.
Capped endpoint rings use curved vector boundaries. Original profile corners remain sharp,
and circular end caps keep uniform flat lighting. Turning Shading off disables lighting.
Smooth lighting follows the same light gizmo, rotation, perspective, preview, Cancel and undo behavior.
SVG and PDF export retain vector paths and gradients; Expand Appearance keeps
those gradients at their original positions when trimming visible surfaces. Non-solid
source paints retain their paint with a gradient shading overlay.
The dialog has **Rotation** and **Lighting** tabs. Rotation groups the profile and view controls. Drag a value or its label
to adjust it, use its slider, or double-click the value to type. Angles show degrees and lighting
values show percentages. **Segments** is in the **Advanced** section. Lighting controls are disabled
when **Shading** is off. A filled dot at the end of a row means the value differs from its default;
click the dot to reset that value. **Reset all** restores every Revolve parameter to its default.
The compact settings dialog opens beside the artboard. With **Preview** enabled, the selected
object has X (red), Y (green) and Z (blue) rotation rings directly on the artboard. Drag a ring to
adjust that axis; drag inside the rings to rotate freely. Hold Shift to snap to 15-degree increments.
The rings and the rotation fields stay in sync. Escape during a drag restores that gesture and
keeps the settings open. Escape again or Cancel restores the document before the dialog opened.
The gizmo appears while editing Revolve; normal source-path selection returns when the dialog closes.
Select the **Lighting** tab to use the light gizmo on the artboard. Drag the sun handle to move
the light on its side of the object: round the centre for its Rotation, towards the centre for a
greater Height. A hollow sun marks a light behind the object. Drag the **Rotation** ring or its label
horizontally to turn the light round the object; drag the **Height** line or its label vertically to
raise or lower it. The labels remain usable when the ring shrinks to a point (Height 90°).
Hold Shift to snap to 15-degree increments. Light gestures update their matching fields without
rotating the object, and keep the same temporary preview, Escape, Cancel and undo behaviour.
Intensity, Softness and Ambient Light are draggable fields and sliders. The Lights list selects which light the gizmo and settings edit; Add Light and Delete Light manage up to ten lights, keeping at least one. Ambient is shared and applied once. Preview, Cancel, Reset all and undo include the whole list.
**Shading** off hides the light gizmo and disables lighting controls. Switch to **Rotation** to return
to the object rings. **Show axis** in **Advanced** displays the source's vertical axis on the object.
Turning **Preview** off restores the original artwork and hides artboard controls until Preview is enabled.
In small windows, the controls scroll while OK and Cancel stay visible. Reset dots restore individual
settings; **Reset all** restores parameters on both tabs.
Preview changes are temporary until OK. Cancel restores the document; OK creates one undo step.
The source anchors remain editable. Appearance lists the effect for reopening its options.
SVG/PDF export evaluates filled vector faces; native saves retain the profile and effect parameters.
**Object > Expand Appearance** replaces the live effect with ordinary editable vector faces.
**Cap** in the shape controls closes the circular rings at the endpoints of an open profile.
It is on by default. Its saved parameter is `cap` (boolean, default true); missing parameters
also use caps. Set it to false to keep the ends open. The reset dot and Reset all restore Cap to on. Each cap is one closed curved vector path from the endpoint ring to the rotation axis,
with uniform flat shading. A full turn produces a projected circular disk (an ellipse in an
orthographic view); a partial turn produces a sector. Body faces share the same curved rim,
so no triangle patches interrupt the cap edge. Caps share the surface's rotation, perspective and paint, and appear in preview,
SVG/PDF export and Expand Appearance. The checkbox has a reset dot and is included in Reset all.
An endpoint on the axis needs no cap. Each open subpath of a compound profile is capped independently.
With an Angle below 360°, Cap also closes the two angular cut sides, so the object appears solid; with Cap
off it is hollow ([Revolve options](https://web.archive.org/web/20210601162814/https://helpx.adobe.com/pdf/illustrator_reference.pdf#page=185)).
Each cut side is flat and uniformly shaded, and is drawn in depth order with the rest of the surface. It covers the
region between each open subpath and the axis, and the area each closed subpath encloses, with one face for each
region. A closed subpath that walls a hole under the object's fill rule leaves that hole open in the face of the
region around it, and the other regions are filled. A self-intersecting subpath fills what the nonzero rule fills,
with one face for each loop it encloses; this is VectorCraft's own rule. A cut side seen edge on is not drawn.
The cut sides appear in preview, SVG/PDF export, Expand Appearance, Expand as Wireframes, Revolve (Classic) and
exported 3D meshes. Cap does not make intersecting profiles into a watertight solid.
In **Advanced**, **Keep visible surfaces only when expanding** is on by default. Expansion removes
completely covered faces and trims partially covered ones using the current rotation and perspective.
Visible interior surfaces through open ends remain. Uncheck it to retain every projected face.
The checkbox has its own reset dot and is included in **Reset all**. Its saved command parameter is
`expandVisibleOnly`; it does not change the live preview or SVG/PDF export baking.
Trimming applies to opaque solid paint. Transparent objects, gradients, patterns, non-normal blending,
later geometry effects and surfaces exceeding bounded visibility limits keep their complete geometry
to preserve their appearance. Visibility follows the same painter order as the live effect, including
its approximation for intersecting surfaces. Uncut faces keep their curved outlines. Visibility calculations use bounded polygon approximations
of curved rims; clipped portions become vector polygons. Expansion changes are undoable
with the standard command.
## Initial limits
- Lighting offers Standard, Diffuse, Top Left and Right, using the [shared original rigs](three-d.md#presets).
Other effective settings show Custom; changing the view does not change the recognized lighting preset.
- Paths, compound paths, type, clipping groups, blends, symbol instances, and groups or layers of them. A clipping group, a blend or a symbol instance sweeps the art it shows about one axis, as described in [three-d.md](three-d.md#clipping-groups-blends-and-symbol-instances). Images must be traced first with Object › Image Trace › Make, and other live objects expanded.
- Open profiles have circular end caps by default, and a partial sweep closes its angular cut sides; turning Cap off keeps both open. Closed profile boundaries are swept as provided.
- One Revolve per source object. Edit its options rather than applying another.
- Object-level Revolve uses the top visible fill, falling back to a stroke. Per-item Revolve uses that item's paint.
- Smooth diffuse shading, one to ten directional lights, no textures, cast shadows or physical materials. Smooth shading interpolates lighting in projected triangles; it does not smooth the silhouette or add specular highlights.
- Faces are drawn back to front by the depths of their centers. When that order draws the nearer of two overlapping faces of a surface first, every pair of overlapping faces goes in the order of their depths at the middle of where they overlap; the sort compares at most 4,000,000 pairs (VectorCraft's own limit), and the pairs past that keep the depths of their centers. Caps facing the camera cover their rim seams; a cap facing away is drawn behind the body except where it is nearer than a body face it overlaps. Intersecting profiles can have incorrect visibility.
- Curves use sixteen samples per segment, and as few as four when a surface would otherwise pass its limits. Surfaces are limited to 16,384 profile points and 163,840 faces, the members of a group together. A straight segment takes one point, a curve takes at least four, and each contour takes one. Smooth shaded side quads become two triangles and share the face limit. A continuous cap retains its original radial mesh cost within this limit, and each region of a cut side counts as one face. Projected ring curves have a 0.001-point fitting tolerance and a shared 32,768-curve limit.
- Axis, bounds and ordinary selection handles continue to refer to the editable 2D source profile.
- Extrude & Bevel, Inflate and Rotate are described in [three-d.md](three-d.md). Materials remain unimplemented.
## Architecture
Revolve geometry in `vectorcraft-three-d` uses `vectorcraft-geom`; the crate also uses `vectorcraft-pathops`
for the other 3D types. It creates a surface of revolution,
applies Euler view rotation, projects it, shades faces and sorts their depth. It has no UI or GPU dependency.
`vectorcraft-effects` turns those faces into document art. The renderer, export baking and
Expand Appearance use the same evaluator. The standard `effect.apply`, `effect.setParams`,
`effect.remove` and `effect.expandAppearance` commands expose it to the CLI, control channel and MCP.
Generated faces include narrow matching strokes to cover antialiasing seams. Their round
joins bound the overlap to half the stroke width, preventing acute triangle corners from
creating spikes along the silhouette in the canvas, SVG/PDF and expanded artwork.
Behaviour references: [public 3D and Materials options](https://helpx.adobe.com/illustrator/desktop/special-effects-styles/create-3d-graphics/3d-materials-panel-options.html) and [public 3D effects documentation](https://helpx.adobe.com/illustrator/desktop/special-effects-styles/create-3d-graphics/create-3d-objects.html).
This implementation uses original mathematics and source code, with no Adobe software, assets or presets.