Point clouds: drawn from their scans, placed, cropped and attached as the reference does

Scans (.rcs) and projects (.rcp) are read and their points drawn as
screen-sized dots, coloured by the cloud's stylization. The cloud's
placement carries its scale and rotation; its extents and crops stay in
the scan's coordinates. A missing scan shows the extents with the saved
path. -POINTCLOUDATTACH / POINTCLOUDATTACH, POINTCLOUDCROP and the
POINTCLOUD* settings follow the reference's prompts and messages, the
Properties list is the reference's, and a locked cloud is left alone by
edits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/app/commands/blocks.rs

@@ -720,6 +720,12 @@ impl OpenCADStudio {
                 self.command_line.push_info(&command.prompt());
                 self.tabs[i].active_cmd = Some(Box::new(command));
             }
+            "POINTCLOUDCROP" => {
+                use crate::command::CadCommand;
+                let command = crate::modules::insert::pc_crop::PointCloudCropCommand::new();
+                self.command_line.push_info(&command.prompt());
+                self.tabs[i].active_cmd = Some(Box::new(command));
+            }
             "IMAGECLIP" => {
                 use crate::command::CadCommand;
                 let command = crate::modules::insert::pdf_clip::PdfClipCommand::image();

src/app/commands/display.rs

@@ -1911,7 +1911,7 @@ impl OpenCADStudio {
             }
 
             "UNDERLAYLAYERS" | "ULAYERS" => self.open_underlay_layers_dialog(i),
-            "POINTCLOUDATTACH" | "RECAP" | "SYNCPVIEWPORTS" => {
+            "RECAP" | "SYNCPVIEWPORTS" => {
                 self.command_line
                     .push_info(crate::tf!("{cmd}: not yet implemented.").as_ref());
             }

src/app/commands/mod.rs

@@ -14,6 +14,7 @@ mod inquiry;
 mod layerprops;
 mod layers;
 pub(crate) mod pdf_import;
+mod point_cloud;
 mod pdf_underlay;
 mod pdf_dialogs;
 mod xclip;
@@ -636,6 +637,21 @@ inventory::submit!(crate::command::CommandRegistration {
         "PDFIMPORTIMAGEPATH",
         "XDWGFADECTL",
         "POINTCLOUDCLIPFRAME",
+        "POINTCLOUDDENSITY",
+        "POINTCLOUDPOINTSIZE",
+        "POINTCLOUDLOCK",
+        "POINTCLOUDAUTOUPDATE",
+        "POINTCLOUDBOUNDARY",
+        "POINTCLOUDRTDENSITY",
+        "POINTCLOUDLOD",
+        "POINTCLOUDPOINTMAX",
+        "POINTCLOUDVISRETAIN",
+        "POINTCLOUDSHADING",
+        "POINTCLOUDCACHESIZE",
+        "POINTCLOUD2DVSDISPLAY",
+        "POINTCLOUDLIGHTING",
+        "POINTCLOUDLIGHTSOURCE",
+        "POINTCLOUDPOINTMAXLEGACY",
         "XCLIPFRAME",
         "WIPEOUTFRAME",
         "FRAMES0",

src/app/commands/point_cloud.rs

@@ -0,0 +1,184 @@
+//! POINTCLOUDATTACH: the point cloud, its definition (one per file, in
+//! ACAD_POINTCLOUD_EX_DICT) and the reactor linking them, added as one undo
+//! step.
+
+use super::*;
+use codec::objects::{
+    ClassObject, ClassObjectData, Dictionary, ObjectType, PointCloudDefinition,
+    PointCloudDefinitionReactor,
+};
+use codec::types::{Handle, Vector3};
+
+use crate::modules::insert::pc_attach::PointCloudPlacement;
+
+const DEFINITIONS: &str = "ACAD_POINTCLOUD_EX_DICT";
+
+fn vector(v: glam::DVec3) -> Vector3 {
+    Vector3::new(v.x, v.y, v.z)
+}
+
+/// The point cloud definitions dictionary under the named-objects root,
+/// created when the drawing has none.
+fn definitions_dictionary(document: &mut codec::CadDocument) -> Option<Handle> {
+    let root = document.header.named_objects_dict_handle;
+    let Some(ObjectType::Dictionary(root_dictionary)) = document.objects.get(&root) else {
+        return None;
+    };
+    if let Some(existing) = root_dictionary.get(DEFINITIONS) {
+        if matches!(document.objects.get(&existing), Some(ObjectType::Dictionary(_))) {
+            return Some(existing);
+        }
+    }
+    let handle = document.allocate_handle();
+    let mut dictionary = Dictionary::new();
+    dictionary.handle = handle;
+    dictionary.owner = root;
+    document.objects.insert(handle, ObjectType::Dictionary(dictionary));
+    if let Some(ObjectType::Dictionary(root_dictionary)) = document.objects.get_mut(&root) {
+        root_dictionary.add_entry(DEFINITIONS, handle);
+    }
+    Some(handle)
+}
+
+/// The definition for a file: the existing one, or a new one registered
+/// under the file's name ("Chair", "Chair(2)" …). Its point count and
+/// extents come from the file.
+fn ensure_definition(
+    document: &mut codec::CadDocument,
+    path: &str,
+    name: &str,
+    points: &crate::scene::model::point_cloud::CloudPoints,
+) -> (Handle, Vector3, Vector3) {
+    let (mut lo, mut hi) = ([f64::MAX; 3], [f64::MIN; 3]);
+    for p in &points.positions {
+        for k in 0..3 {
+            lo[k] = lo[k].min(p[k]);
+            hi[k] = hi[k].max(p[k]);
+        }
+    }
+    let (min, max) = if points.positions.is_empty() {
+        (Vector3::ZERO, Vector3::ZERO)
+    } else {
+        (Vector3::new(lo[0], lo[1], lo[2]), Vector3::new(hi[0], hi[1], hi[2]))
+    };
+    let same = |stored: &str| stored.replace('/', "\\").eq_ignore_ascii_case(&path.replace('/', "\\"));
+    let existing = document.objects.iter().find_map(|(handle, object)| match object {
+        ObjectType::ClassObject(object) => match &object.data {
+            ClassObjectData::PointCloudDefinitionEx(def) if same(&def.source_filename) => Some(*handle),
+            _ => None,
+        },
+        _ => None,
+    });
+    if let Some(handle) = existing {
+        return (handle, min, max);
+    }
+    let handle = document.allocate_handle();
+    let mut definition = ClassObject::new(ClassObjectData::PointCloudDefinitionEx(PointCloudDefinition {
+        class_version: 1,
+        source_filename: path.to_string(),
+        is_loaded: true,
+        point_count: points.positions.len() as i64,
+        extents_min: min,
+        extents_max: max,
+    }));
+    definition.handle = handle;
+    if let Some(dictionary) = definitions_dictionary(document) {
+        definition.owner = dictionary;
+        definition.reactors.push(dictionary);
+        if let Some(ObjectType::Dictionary(entries)) = document.objects.get_mut(&dictionary) {
+            let mut key = name.to_string();
+            let mut suffix = 1;
+            while entries.get(&key).is_some() {
+                suffix += 1;
+                key = format!("{name}({suffix})");
+            }
+            entries.add_entry(key, handle);
+        }
+    }
+    document.objects.insert(handle, ObjectType::ClassObject(definition));
+    (handle, min, max)
+}
+
+impl OpenCADStudio {
+    pub(crate) fn attach_point_cloud(&mut self, i: usize, label: String, placement: PointCloudPlacement) {
+        let Some(points) = crate::scene::model::point_cloud::load(&placement.path) else {
+            self.command_line.push_error("All scans are not found or invalid.");
+            self.command_line.push_error("Attach point cloud failed");
+            return;
+        };
+        let path = placement.path.to_string_lossy().into_owned();
+        let name = placement
+            .path
+            .file_stem()
+            .map(|stem| stem.to_string_lossy().into_owned())
+            .unwrap_or_default();
+        let pending = self.begin_undo(i, label, 1, false);
+        let document = &mut self.tabs[i].scene.document;
+        // POINTCLOUDLOCK 1 attaches clouds locked.
+        let locked = crate::scene::model::point_cloud::setting("POINTCLOUDLOCK")
+            .is_some_and(|setting| crate::scene::model::point_cloud::setting_value(document, setting) == 1);
+        let (definition, extents_min, extents_max) = ensure_definition(document, &path, &name, &points);
+        let [x, y, z] = placement.axes;
+        // As the reference creates a cloud: scan colours, the intensity
+        // range 0–100 as a gradient, crops shown.
+        let data = codec::entities::PointCloudExData {
+            class_version: 1,
+            extents_min,
+            extents_max,
+            ucs_origin: vector(placement.insertion),
+            ucs_x_direction: vector(x),
+            ucs_y_direction: vector(y),
+            ucs_z_direction: vector(z),
+            locked,
+            definition_handle: definition,
+            reactor_handle: Handle::NULL,
+            name,
+            show_intensity: false,
+            show_cropping: true,
+            unknown_bl0: 0,
+            unknown_bl1: 0,
+            stylization_type: 1,
+            intensity_color_scheme: String::new(),
+            current_color_scheme: String::new(),
+            classification_color_scheme: String::new(),
+            elevation_min: 0.0,
+            elevation_max: 0.0,
+            intensity_min: 0,
+            intensity_max: 100,
+            intensity_out_of_range_behavior: 1,
+            elevation_out_of_range_behavior: 1,
+            elevation_apply_to_fixed_range: false,
+            intensity_as_gradient: true,
+            elevation_as_gradient: false,
+            croppings: Vec::new(),
+        };
+        let entity = codec::EntityType::Extended(codec::entities::ExtendedEntity {
+            common: codec::entities::EntityCommon::new(),
+            data: codec::entities::ExtendedEntityData::PointCloudEx(data),
+        });
+        if let Some(cloud) = self.commit_entity_handle(entity) {
+            // The reactor, owned by the cloud, tells the definition who uses it.
+            let document = &mut self.tabs[i].scene.document;
+            let reactor = document.allocate_handle();
+            let mut object = ClassObject::new(ClassObjectData::PointCloudDefinitionReactorEx(
+                PointCloudDefinitionReactor { class_version: 1 },
+            ));
+            object.handle = reactor;
+            object.owner = cloud;
+            document.objects.insert(reactor, ObjectType::ClassObject(object));
+            if let Some(ObjectType::ClassObject(definition)) = document.objects.get_mut(&definition) {
+                definition.reactors.push(reactor);
+            }
+            if let Some(codec::EntityType::Extended(extended)) = document.get_entity_mut(cloud) {
+                if let codec::entities::ExtendedEntityData::PointCloudEx(data) = &mut extended.data {
+                    data.reactor_handle = reactor;
+                }
+            }
+            self.command_line.push_output("1 point cloud attached");
+        }
+        self.tabs[i].dirty = true;
+        if let Some(pd) = pending {
+            self.commit_undo_delta(i, pd);
+        }
+    }
+}

src/app/commands/styleprops.rs

@@ -1031,6 +1031,21 @@ impl OpenCADStudio {
                     | "PDFIMPORTIMAGEPATH"
                     | "XDWGFADECTL"
                     | "POINTCLOUDCLIPFRAME"
+                    | "POINTCLOUDDENSITY"
+                    | "POINTCLOUDPOINTSIZE"
+                    | "POINTCLOUDLOCK"
+                    | "POINTCLOUDAUTOUPDATE"
+                    | "POINTCLOUDBOUNDARY"
+                    | "POINTCLOUDRTDENSITY"
+                    | "POINTCLOUDLOD"
+                    | "POINTCLOUDPOINTMAX"
+                    | "POINTCLOUDVISRETAIN"
+                    | "POINTCLOUDSHADING"
+                    | "POINTCLOUDCACHESIZE"
+                    | "POINTCLOUD2DVSDISPLAY"
+                    | "POINTCLOUDLIGHTING"
+                    | "POINTCLOUDLIGHTSOURCE"
+                    | "POINTCLOUDPOINTMAXLEGACY"
                     | "XCLIPFRAME"
                     | "WIPEOUTFRAME"
                     | "HALOGAP"
@@ -1096,6 +1111,39 @@ impl OpenCADStudio {
                         crate::t!("SETVAR: CETRANSPARENCY LTSCALE CELTSCALE PDMODE PDSIZE TEXTSIZE ORTHOMODE FILLMODE MIRRTEXT FRAME IMAGEFRAME PDFFRAME WIPEOUTFRAME XCLIPFRAME POINTCLOUDCLIPFRAME ZOOMWHEEL ZOOMFACTOR SHORTCUTMENU SHORTCUTMENUDURATION CURSORSIZE PICKBOX CURSORTYPE SNAPANG TEXTFILL CLIPROMPTLINES COMMANDLINEFADETIME ATTREQ ATTDIA DIMASSOC DIMCONTINUEMODE CONSTRAINTSOLVEMODE CONSTRAINTINFER CONSTRAINTBARDISPLAY CONSTRAINTBARMODE CONSTRAINTNAMEFORMAT DYNCONSTRAINTDISPLAY ANGBASE ANGDIR SKETCHINC SKPOLY SKTOLERANCE DONUTID DONUTOD CENTEREXE CENTERLAYER CENTERLTYPE CENTERLTSCALE CENTERLTYPEFILE CENTERCROSSSIZE CENTERCROSSGAP CENTERMARKEXE COLORTHEME SELECTIONAREA SELECTIONAREAOPACITY SELECTIONEFFECT SELECTIONEFFECTCOLOR WINDOWSAREACOLOR CROSSINGAREACOLOR SELECTIONPREVIEW GRIPSIZE GRIPCOLOR GRIPHOT GRIPHOVER GRIPOBJLIMIT | CLAYER CELTYPE TEXTSTYLE (read-only)").as_ref(),
                     );
                 } else {
+                    // Point cloud settings, kept with the drawing.
+                    if let Some(setting) = crate::scene::model::point_cloud::setting(&name) {
+                        let document = &self.tabs[i].scene.document;
+                        let current = crate::scene::model::point_cloud::setting_value(document, setting);
+                        match value.as_deref().map(|value| setting.check(value)) {
+                            Some(Ok(new)) => {
+                                if new != current {
+                                    crate::io::set_drawing_variable(
+                                        &mut self.tabs[i].scene.document,
+                                        setting.name,
+                                        &new.to_string(),
+                                    );
+                                    self.tabs[i].scene.bump_geometry();
+                                    self.tabs[i].dirty = true;
+                                }
+                            }
+                            // Refused: say why, and ask again unless the value ends it.
+                            Some(Err(refusal)) => {
+                                for line in &refusal.lines {
+                                    self.command_line.push_error(line);
+                                }
+                                if refusal.ask_again {
+                                    self.command_line.push_output(&format!("Enter new value for {name} <{current}>:"));
+                                    self.pending_setvar = Some(name.clone());
+                                }
+                            }
+                            None => {
+                                self.command_line.push_output(&format!("Enter new value for {name} <{current}>:"));
+                                self.pending_setvar = Some(name.clone());
+                            }
+                        }
+                        return Some(self.finish_dispatch(cmd));
+                    }
                     if name == "XDWGFADECTL" {
                         let current = crate::scene::cache::block_cache::xref_fade_ctl();
                         if let Some(value) = &value {

src/app/commands/xref_attach.rs

@@ -57,6 +57,19 @@ impl OpenCADStudio {
                 self.start_underlay_attach(i, codec::entities::UnderlayType::Dgn, rest);
                 Some(Task::none())
             }
+            // POINTCLOUDATTACH picks the file; with a file, or as
+            // -POINTCLOUDATTACH, it asks on the command line.
+            ("POINTCLOUDATTACH", true) => Some(Task::done(Message::PointCloudAttachPick)),
+            ("POINTCLOUDATTACH" | "-POINTCLOUDATTACH", _) => {
+                use crate::command::CadCommand;
+                let command = crate::modules::insert::pc_attach::PointCloudAttachCommand::new();
+                self.command_line.push_info(&command.prompt());
+                self.tabs[i].active_cmd = Some(Box::new(command));
+                if !rest.is_empty() {
+                    return Some(self.feed_command(crate::command::StepInput::Text(rest.to_string())));
+                }
+                Some(Task::none())
+            }
             ("XATTACH", true) => Some(Task::done(Message::XAttachPick)),
             // A file named on the command line skips the picker.
             // Handled at once, so the placement it starts belongs to this
@@ -355,6 +368,21 @@ impl OpenCADStudio {
                 },
                 Message::AttachPickResult,
             ),
+            Message::PointCloudAttachPick => Task::perform(
+                async {
+                    let handle = crate::sys::file_dialog()
+                        .set_title(crate::t!("Select Point Cloud File").as_ref())
+                        .add_filter(crate::t!("Point Cloud Project").as_ref(), &["rcp"])
+                        .add_filter(crate::t!("Point Cloud Scan").as_ref(), &["rcs"])
+                        .pick_file()
+                        .await;
+                    match handle {
+                        Some(h) => Ok(crate::sys::handle_path(&h)),
+                        None => Err("Cancelled".to_string()),
+                    }
+                },
+                Message::AttachPickResult,
+            ),
             Message::AttachPick => Task::perform(
                 async {
                     let handle = crate::sys::file_dialog()
@@ -363,7 +391,7 @@ impl OpenCADStudio {
                             crate::t!("All Reference Files").as_ref(),
                             &[
                                 "dwg", "dxf", "pdf", "dwf", "dwfx", "dgn", "png", "jpg", "jpeg",
-                                "bmp", "tif", "tiff",
+                                "bmp", "tif", "tiff", "rcp", "rcs",
                             ],
                         )
                         .add_filter(crate::t!("Drawing").as_ref(), &["dwg", "dxf"])
@@ -374,6 +402,7 @@ impl OpenCADStudio {
                             crate::t!("Images").as_ref(),
                             &["png", "jpg", "jpeg", "bmp", "tif", "tiff"],
                         )
+                        .add_filter(crate::t!("Point Clouds").as_ref(), &["rcp", "rcs"])
                         .pick_file()
                         .await;
                     match handle {
@@ -423,6 +452,21 @@ impl OpenCADStudio {
                         }
                         Task::none()
                     }
+                    // A point cloud goes on to its placement prompts.
+                    "rcp" | "rcs" => {
+                        use crate::command::CadCommand;
+                        let i = self.active_tab;
+                        if crate::scene::model::point_cloud::load(&path).is_none() {
+                            self.command_line.push_error("All scans are not found or invalid.");
+                            self.command_line.push_error("Attach point cloud failed");
+                            return Task::none();
+                        }
+                        let command =
+                            crate::modules::insert::pc_attach::PointCloudAttachCommand::with_file(path);
+                        self.command_line.push_info(&command.prompt());
+                        self.tabs[i].active_cmd = Some(Box::new(command));
+                        Task::none()
+                    }
                     "png" | "jpg" | "jpeg" | "bmp" | "tif" | "tiff" => {
                         let result = image::image_dimensions(&path)
                             .map(|(w, h)| (path.clone(), w, h))