Revision Clouds — Create and modify revision clouds (markup) - AutoCAD

SECTION 1

Historical Context & Motivation

Before the era of digital drafting, engineers and architects communicated design changes by physically drawing freehand, wavy-edged enclosures around modified regions on paper blueprints. These hand-drawn markings, known as revision clouds, served as an immediately recognizable visual signal that something within the enclosed area had been altered. The convention was universally adopted across disciplines—from structural engineering to electrical schematics—because its irregular, cloud-like border is unmistakable even in dense, detail-heavy drawings. As CAD software matured through the 1990s and 2000s, the revision cloud transitioned from a manual drafting convention to an automated digital tool, preserving the same visual semantics while adding parametric control over arc size, shape, and layer assignment.

1960s • Manual Markup Era

Drafters use freehand wavy lines on vellum and blueprint copies to circle areas requiring revision. No formal standard exists; conventions vary by firm.

1982 • AutoCAD 1.0 Released

Autodesk releases AutoCAD, digitizing the drafting process. Revision clouds initially must be drawn manually using polylines or arcs, mimicking paper-era workflows.

2004 • REVCLOUD Command Introduced

AutoCAD introduces the dedicated REVCLOUD command, allowing users to draw revision clouds with controllable minimum and maximum arc lengths, greatly accelerating markup workflows.

2016 • Revision Clouds as Native Objects

AutoCAD 2016 elevates revision clouds to first-class objects with grip editing, conversion from existing geometry, and integration with sheet set revision tracking.

2020s • Cloud-Based Collaboration

AutoCAD web and mobile apps support revision cloud creation, enabling real-time collaborative markup across distributed engineering teams using Autodesk Docs.

The fundamental question that revision clouds address is deceptively simple: how do you efficiently direct a reviewer's attention to exactly the portions of a drawing that have changed? In a complex floor plan or circuit schematic containing thousands of entities, textual change logs alone are insufficient. Revision clouds provide a spatial, visual index that maps change descriptions to their geometric locations, bridging the gap between documentation metadata and the drawing itself.

SECTION 2

Core Principles & Definitions

A revision cloud in AutoCAD is a closed polyline composed of sequential arcs whose bulge directions create the characteristic scalloped appearance. Understanding revision clouds requires grasping several foundational concepts that govern their creation, appearance, and integration into documentation workflows.

REVCLOUD Command

The primary command for creating revision clouds. Invoked via REVCLOUD at the command line, it offers options for freehand drawing, rectangular, polygonal, or conversion from existing objects.

Arc Length Parameters

The minimum and maximum arc lengths control the visual density of the scalloped edge. Smaller arcs produce a tighter, more detailed cloud; larger arcs yield a looser, bolder appearance appropriate for large-scale drawings.

Cloud Styles

AutoCAD supports two styles: Normal (arcs bulge outward) and Calligraphy (arcs vary in thickness to simulate a calligraphic pen). Style selection affects visual impact.

Object Conversion

Existing closed geometry—circles, rectangles, polylines, ellipses—can be converted into revision clouds via the Object option, preserving the shape while applying the scalloped edge treatment.

Layer & Revision Tracking

Best practice places revision clouds on dedicated layers (e.g., G-ANNO-REVS) with distinct colors per revision number, enabling toggling visibility by revision iteration.

✦

KEY TAKEAWAY

Think of a revision cloud like a diff highlight in a version control system such as Git. Just as a code diff marks changed lines with color to help reviewers focus on modifications without re-reading the entire file, a revision cloud spatially marks changed regions in a drawing so that a reviewer can skip unchanged areas and focus on what matters. The cloud's boundary is the geometric equivalent of a @@ hunk header—it tells you where to look.

SECTION 3

Visual Explanation

Anatomy of a Revision Cloud

The diagram shows a revision cloud enclosing a modified region of a floor plan. On the right, key parameters are listed alongside a magnified view of individual arc segments, illustrating how chord length and bulge define the scalloped appearance.

In the diagram above, the revision cloud encloses two rooms and a corridor that have been redesigned. The cloud's boundary is constructed from a sequence of arc segments, each defined by its chord length (the straight-line distance between arc endpoints) and bulge factor (the perpendicular deviation from the chord to the arc's apex). AutoCAD's REVCLOUD command automatically generates these arcs as the user traces the cloud boundary, ensuring uniform visual density. The min and max arc length parameters provide a range within which the software interpolates, producing natural-looking variation rather than a mechanically uniform edge.

SECTION 4

How Revision Clouds Work Internally

Under the hood, a revision cloud is stored as a lightweight polyline (LWPOLYLINE entity) with arc segments defined by bulge values at each vertex. Understanding the mathematical relationship between arc length, bulge, and the resulting visual presentation helps when you need to script cloud creation via AutoLISP or the .NET API, or when you must conform to firm-specific CAD standards that dictate exact arc dimensions.

ARC BULGE FACTOR

bulge = tan(θ / 4)

Where θ is the included angle of the arc segment (in radians). A bulge of 1.0 corresponds to a semicircle (θ = π). Revision clouds typically use bulge values between 0.5 and 1.0, producing arcs that span 90° to 180°.

ARC RADIUS FROM CHORD AND BULGE

r = (c / 2) × (1 + b²) / (2 × b)

Where r is the arc radius, c is the chord length (approximately equal to the arc length parameter), and b is the bulge value. This formula is essential when programmatically generating clouds with specific visual properties.

NUMBER OF ARCS ALONG A SEGMENT

n = ⌈L / a_avg⌉

Where n is the number of arc segments, L is the total boundary path length, and a_avg = (a_min + a_max) / 2 is the average arc length. The ceiling function ensures complete coverage of the boundary.

💡

Developer Note

When scripting revision clouds via AutoLISP, the (command "REVCLOUD" "A" minArc maxArc ...) sequence lets you set arc parameters programmatically. In the .NET API, you construct an Autodesk.AutoCAD.DatabaseServices.Polyline with alternating bulge signs to achieve the scalloped effect. Understanding the bulge math above is critical for correct programmatic generation.

SECTION 5

Detailed Breakdown of Creation Methods

AutoCAD provides multiple pathways for creating and modifying revision clouds, each suited to different workflow scenarios. The choice of method depends on whether you are marking up a region freehand, enclosing a precise geometric area, or converting existing geometry into a revision indicator. The following diagram and table detail these methods systematically.

Flowchart of the REVCLOUD command's four creation pathways—Freehand, Rectangular, Polygonal, and Object Conversion—along with post-creation modification operations.

Method	Command Option	Best Use Case	Precision Level
Freehand	Default (trace with cursor)	Quick, informal markups during design review meetings	Low — depends on cursor path
Rectangular	`R`	Marking up grid-aligned regions, room boundaries, or detail callouts	High — snaps to coordinate pairs
Polygonal	`P`	Irregular regions that don't fit a rectangle—e.g., L-shaped zones	Medium — vertex-based control
Object Convert	`O`	Converting pre-drawn closed polylines, circles, or ellipses into clouds	Highest — inherits source geometry

Comparison of REVCLOUD creation methods

SECTION 6

Worked Example — Creating and Modifying a Revision Cloud

Suppose you are working on an architectural floor plan (drawing units in inches, scale 1:48) and a client has requested that a conference room be widened by 2 feet. You need to mark the affected area with a revision cloud on the appropriate layer with arc lengths scaled to the drawing.

Mark a Design Change with a Rectangular Revision Cloud

1
Step 1 — Determine Appropriate Arc Length

At a 1:48 scale, a printed arc length of approximately 3/16" translates to a model-space arc length of 0.1875 × 48 = 9 inches. Set the minimum arc length to 6 and the maximum to 12 (inches) for a natural appearance at this scale.

Min arc = 6", Max arc = 12"
2
Step 2 — Set the Current Layer

Before invoking REVCLOUD, set the current layer to your revision tracking layer. Type -LAYER → S → G-ANNO-REVS-R01 at the command line, or use the Layer dropdown. This layer should be colored red or magenta per your firm's standards to distinguish it from design geometry.

Current layer: G-ANNO-REVS-R01
3
Step 3 — Invoke REVCLOUD with Arc Length and Rectangular Options

Type REVCLOUD → press Enter. At the prompt, type A to set arc length → enter 6 for minimum → enter 12 for maximum. Then type R to select the Rectangular method.

Arc length set; Rectangular mode active
4
Step 4 — Specify the Cloud Boundary

Click the first corner point at the lower-left of the conference room area (e.g., coordinate 120,84), then click the opposite corner at the upper-right (e.g., 288,204). AutoCAD generates the scalloped cloud boundary enclosing the 168" × 120" region. Use OSNAP endpoints or intersections for precision.

Revision cloud created: 168" × 120" rectangle with ~64 arc segments
5
Step 5 — Verify and Modify

Select the cloud and open the Properties palette (Ctrl+1). Confirm the layer assignment, color, and arc parameters. If the cloud needs reshaping—say the change actually extends into the adjacent hallway—use grip editing: click the cloud to reveal grips, then drag a grip vertex to expand the boundary. Alternatively, delete and re-create using the Polygonal method for an L-shaped region.

Cloud verified on correct layer; grips available for reshaping

SECTION 7

Revision Clouds vs. Other Markup Methods

Revision clouds are not the only markup mechanism available in AutoCAD. Understanding their strengths and limitations relative to alternatives helps you choose the right tool for each documentation scenario. The table below compares revision clouds against common alternatives: MTEXT annotations, wipeouts with text, and the markup tools in Autodesk Docs.

Feature	Revision Clouds	MTEXT Annotations	Autodesk Docs Markup
Spatial Clarity	Excellent — visually encloses the exact changed region	Poor — text floats without spatial boundary	Good — supports cloud, arrow, and text overlays
Embedded in DWG	Yes — native polyline entity	Yes — native MTEXT entity	No — stored as a separate overlay in Autodesk cloud
Printable	Yes — fully controllable via layer visibility	Yes	Requires export to PDF with markup layer
Scriptable (API)	Yes — AutoLISP, .NET, Python (via pyautocad)	Yes — full API support	Limited — REST API for Autodesk Forge
Change Description	No — indicates location only; pair with revision table	Yes — contains descriptive text	Yes — supports threaded comments

Comparison of markup methods in AutoCAD workflows

✦

KEY TAKEAWAY

Revision clouds and descriptive annotations are complementary, not competing, tools—similar to how in software engineering you use both inline code comments and commit messages. The cloud marks where a change occurred (like a diff highlight), while a revision table or text note explains what changed (like a commit message). Best practice always uses both in tandem.

SECTION 8

Connection to Advanced Documentation Workflows

Revision clouds in isolation are useful, but their true power emerges when integrated into a broader document management ecosystem. In professional practice, revision clouds tie into revision tables, sheet sets, and BIM coordination workflows. For computer science students interested in CAD automation, this integration represents an opportunity to build tooling that programmatically manages revision state across large drawing sets.

Aspect	Basic Revision Clouds	Integrated Revision Management
Tracking	Manual — user assigns layer names with revision numbers	Automated — revision number, date, and description linked to cloud via revision table block
Scope	Per-drawing	Cross-sheet via Sheet Set Manager; revision data propagates to title blocks
Automation	None — entirely manual creation	Scripts (AutoLISP/.NET) auto-generate clouds from comparison between drawing versions
Collaboration	File sharing via email or shared drive	Autodesk Docs / BIM 360 with real-time markup synchronization

Basic vs. integrated revision management

Looking forward, Autodesk's investment in cloud-based collaboration and the Forge/APS platform means that revision cloud metadata will increasingly be accessible via REST APIs. Computer science students with CAD domain knowledge are well-positioned to build tools that automate revision tracking—for example, a CI/CD-style pipeline that compares DWG versions, computes geometric differences, and auto-generates revision clouds at the diff locations, analogous to how automated testing frameworks flag regressions in code.

SECTION 9

Practice Problems

Question 1: CONCEPTUAL

Explain why revision clouds use scalloped (arc-based) boundaries rather than simple rectangles or circles to indicate changed regions. What cognitive and perceptual advantages does the cloud shape provide in a dense, complex drawing?

Show answer

The scalloped boundary creates a visually distinctive pattern that is immediately recognizable as a markup element rather than design geometry. In a dense drawing containing hundreds of rectangles, circles, and polylines, a plain rectangle around a changed region would be easily confused with actual design entities. The irregular, wave-like arcs of a revision cloud leverage the Gestalt principle of figure-ground segregation—their organic form stands out against the typically geometric content of engineering drawings. Additionally, the cloud's visual language is a cross-disciplinary convention, meaning that reviewers from any background instantly recognize its purpose without needing annotation.

Question 2: BASIC CALCULATION

A revision cloud encloses a rectangular region measuring 200 units × 150 units. If the average arc length is set to 10 units, approximately how many arc segments will AutoCAD generate along the cloud boundary? Show your calculation.

Show answer

The perimeter of the rectangle is P = 2 × (200 + 150) = 700 units. Using the formula n = ⌈L / a_avg⌉, we get n = ⌈700 / 10⌉ = 70 arc segments. In practice, the actual number may vary slightly because AutoCAD distributes arcs with lengths randomly varying between the specified minimum and maximum, and corner transitions may introduce slight deviations. However, 70 is a solid estimate for planning purposes—for instance, you might use this to assess whether the cloud will appear appropriately dense at the intended plot scale.

Question 3: INTERMEDIATE

You are preparing a drawing at 1:100 metric scale (drawing in millimeters, plotting at 1:100). You want the printed revision cloud arcs to appear approximately 3 mm long on paper. Calculate the appropriate model-space arc length. Then describe the complete REVCLOUD command sequence, including setting the arc length and using the Polygonal method to enclose an L-shaped region.

Show answer

At 1:100 scale, a 3 mm printed arc corresponds to 3 × 100 = 300 mm in model space. The command sequence is: (1) Type REVCLOUD and press Enter. (2) Type A for arc length, then enter 200 for minimum and 400 for maximum (centering on 300 mm). (3) Type P for Polygonal. (4) Click successive vertices tracing the L-shape boundary—for example, six vertices defining the two-rectangle composite that forms the L. (5) Type C or return to the first point to close the polygon. AutoCAD converts the polygon into a closed polyline with scalloped arcs. The cloud will contain approximately ⌈P / 300⌉ arcs, where P is the total perimeter of the L-shape.

Question 4: APPLIED

You are developing an AutoLISP script that automates revision cloud creation. The script should: (a) prompt the user for a revision number, (b) create or set the layer to a name formatted as "REVCLOUD-R##" with color index corresponding to the revision number (R01=Red/1, R02=Yellow/2, R03=Green/3), and (c) invoke REVCLOUD in rectangular mode with arc lengths of 6 and 12. Write pseudocode for this script and identify which AutoLISP functions you would use for each step.

Show answer

Pseudocode: (1) Use (getint " Revision number: ") to capture the revision number into variable rev_num. (2) Format the layer name using (strcat "REVCLOUD-R" (if (< rev_num 10) (strcat "0" (itoa rev_num)) (itoa rev_num))). (3) Use (command "-LAYER" "M" layer_name "C" rev_num layer_name "") to create and set the layer with the appropriate color index. (4) Use (command "REVCLOUD" "A" 6 12 "R") to set arc lengths and enter rectangular mode. (5) Use (getpoint) twice or let the user interactively pick corners. Key AutoLISP functions: getint for input, strcat and itoa for string formatting, command for invoking AutoCAD commands. Error handling via (if (null rev_num) (alert "Invalid input")) ensures robustness.

Question 5: CRITICAL THINKING

Consider the analogy between revision clouds in CAD and diff/patch systems in version control (e.g., Git). Design a hypothetical automated system that compares two versions of a DWG file and generates revision clouds at the locations of geometric differences. What data structures and algorithms would you use? What are the key challenges, and how would you handle edge cases such as entities that moved versus entities that were modified in place?

Show answer

The system would operate in three phases: (1) Entity extraction: Parse both DWG versions using the Open Design Alliance (ODA) SDK or Autodesk's ObjectARX, building a spatial index (R-tree or quadtree) of all entities with their handles, geometric properties, and bounding boxes. (2) Differencing: Perform entity-level matching using handles as primary keys and geometric similarity (Hausdorff distance) as a fallback for entities with changed handles. Classify differences as additions (handle exists only in new version), deletions (handle exists only in old), modifications (same handle, different geometry), and moves (same geometry, different insertion point). (3) Cloud generation: For each difference cluster, compute a bounding polygon using a convex hull or alpha-shape algorithm, then invoke REVCLOUD programmatically with the Object conversion option on that polygon. Key challenges include: disambiguating moves from delete+add pairs (solvable via bipartite matching on geometric fingerprints), handling exploded/regrouped blocks, and setting appropriate arc lengths based on the spatial extent of each diff cluster. Edge cases like overlapping changes could be merged using polygon union operations before cloud generation.

SUMMARY

Lesson Summary

Summary

Revision clouds are AutoCAD's primary tool for spatial change markup, providing an immediately recognizable scalloped boundary that directs reviewers to modified drawing regions. Created via the REVCLOUD command, they support four creation methods—Freehand, Rectangular, Polygonal, and Object Conversion—each suited to different precision requirements and region shapes. The visual density of the cloud edge is controlled by minimum and maximum arc length parameters, which must be scaled according to the drawing's plot scale to ensure consistent printed appearance.

Internally, revision clouds are closed lightweight polylines with bulge-defined arc segments, making them fully scriptable via AutoLISP and the .NET API. Best practice assigns clouds to dedicated, color-coded layers per revision number and pairs them with revision tables that provide textual descriptions of each change. As CAD workflows increasingly move to cloud-based platforms, revision clouds are evolving from standalone markup entities into nodes within integrated document management and BIM coordination systems, offering rich opportunities for automation by computer science professionals.