-VIEW sEttings Background dialog and view backgrounds

Color, Gradient and Image at the background prompt open a Background
dialog (None / Solid / Gradient / Image, preview, solid colour, two- or
three-colour gradient with rotation, image file with position and
scale). Apply links the view to a new background object in
ACAD_BACKGROUND; restoring a view gives the model viewport a copy of
it (or none), and saving a view copies the viewport's background.

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

src/app/commands/pdf_dialogs.rs

@@ -439,6 +439,7 @@ impl OpenCADStudio {
                     "attach" => crate::t!("Attaches a PDF file as an underlay."),
                     "pointcloud" => crate::t!("Attaches a point cloud scan or project."),
                     "pcsection" => crate::t!("Traces the points on the kept side of a live section as lines."),
+                    "background" => std::borrow::Cow::Owned(crate::tr!("view-background", "help")),
                     "pointcloudcolormap" => {
                         crate::t!("Sets the color schemes and ranges a point cloud is colored by intensity or elevation.")
                     }
@@ -572,6 +573,16 @@ impl OpenCADStudio {
             | PdfDialogMsg::MapCurrent(_)
             | PdfDialogMsg::MapApply
             | PdfDialogMsg::MapOk) => return self.update_point_cloud_color_map(message),
+            message @ (PdfDialogMsg::BgKind(_)
+            | PdfDialogMsg::BgPickColor(_)
+            | PdfDialogMsg::BgColor(..)
+            | PdfDialogMsg::BgThree(_)
+            | PdfDialogMsg::BgRotation(_)
+            | PdfDialogMsg::BgImage(_)
+            | PdfDialogMsg::BgBrowse
+            | PdfDialogMsg::BgPosition(_)
+            | PdfDialogMsg::BgAspect(_)
+            | PdfDialogMsg::BgApply) => return self.update_view_background(message),
             message @ (PdfDialogMsg::SecPerimeter(_)
             | PdfDialogMsg::SecMaxPoints(_)
             | PdfDialogMsg::SecLayer(_)

src/app/commands/view_presets.rs

@@ -111,7 +111,7 @@ impl OpenCADStudio {
     }
 
     /// Carry out what -VIEW gathered (`-VIEW >VERB args`).
-    pub(super) fn run_dash_view(&mut self, rest: &str, i: usize) -> Task<Message> {
+    pub(crate) fn run_dash_view(&mut self, rest: &str, i: usize) -> Task<Message> {
         let (verb, arg) = rest.split_once(' ').unwrap_or((rest, ""));
         let mut settings_again = false;
         match verb {
@@ -197,6 +197,14 @@ impl OpenCADStudio {
                 }
             }
             "SETTINGS" => settings_again = true,
+            // Background type chosen: its dialog takes over until Apply or Cancel.
+            "BACKGROUND" => {
+                if let Some((view, kind)) = arg.split_once('\u{1f}') {
+                    self.open_view_background(i, view, kind);
+                    return self.finish_dispatch("-VIEW");
+                }
+                settings_again = true;
+            }
             "UCSVIEW" => {
                 view_cmd::set_ucs_view(arg == "1");
                 self.save_config();
@@ -245,14 +253,20 @@ impl OpenCADStudio {
     /// of a view saved again under the same name.
     fn save_named_view(&mut self, i: usize, mut view: codec::tables::View) {
         self.push_undo_snapshot(i, "-VIEW");
+        let background = self.tabs[i].scene.active_background();
         let document = &mut self.tabs[i].scene.document;
+        view.background_handle = crate::scene::copy_background(document, background);
         match document.views.get(&view.name).cloned() {
             Some(old) => {
                 view.name = old.name;
                 view.handle = old.handle;
                 view.visual_style_handle = old.visual_style_handle;
                 view.live_section_handle = old.live_section_handle;
-                view.background_handle = old.background_handle;
+                // The view keeps its background unless the viewport has
+                // one, which the view then takes a copy of.
+                if view.background_handle.is_null() {
+                    view.background_handle = old.background_handle;
+                }
             }
             None => {
                 view.handle = document.allocate_handle();
@@ -339,3 +353,193 @@ impl OpenCADStudio {
         self.tabs[i].dirty = true;
     }
 }
+
+impl OpenCADStudio {
+    /// The Background dialog for a named view, on the type typed at the
+    /// prompt and filled from the view's background where it has one.
+    fn open_view_background(&mut self, i: usize, view: &str, kind: &str) {
+        use crate::ui::window::pdf_dialogs::{BgKind, BgPosition, ViewBackgroundState};
+        use codec::objects::ClassObjectData as D;
+        let unpack = |c: u32| [(c >> 16) as u8, (c >> 8) as u8, c as u8];
+        let canvas = self.tabs[i].scene.bg_color;
+        let mut state = ViewBackgroundState {
+            view: view.to_string(),
+            kind: match kind {
+                "SOLID" => BgKind::Solid,
+                "GRADIENT" => BgKind::Gradient,
+                "IMAGE" => BgKind::Image,
+                _ => BgKind::None,
+            },
+            // The reference's defaults.
+            solid: [128, 128, 255],
+            top: [204, 204, 204],
+            middle: [128, 128, 128],
+            bottom: [51, 51, 51],
+            three: false,
+            rotation: "0".into(),
+            image: String::new(),
+            position: BgPosition::Center,
+            aspect: false,
+            canvas: [0, 1, 2].map(|k| (canvas[k].clamp(0.0, 1.0) * 255.0).round() as u8),
+        };
+        let document = &self.tabs[i].scene.document;
+        let current = document.views.get(view).map_or(Handle::NULL, |v| v.background_handle);
+        if let Some(ObjectType::ClassObject(object)) = document.objects.get(&current) {
+            match &object.data {
+                D::SolidBackground(value) => state.solid = unpack(value.color),
+                D::GradientBackground(value) => {
+                    (state.top, state.middle, state.bottom) = (
+                        unpack(value.color_top),
+                        unpack(value.color_middle),
+                        unpack(value.color_bottom),
+                    );
+                    state.three = value.height > 0.0;
+                    state.rotation = crate::ui::window::pdf_dialogs::short(value.rotation);
+                }
+                D::ImageBackground(value) => {
+                    state.image = value.filename.clone();
+                    state.position = if value.use_tiling {
+                        BgPosition::Tile
+                    } else if value.fit_to_screen {
+                        BgPosition::Stretch
+                    } else {
+                        BgPosition::Center
+                    };
+                    state.aspect = value.maintain_aspect_ratio;
+                }
+                _ => {}
+            }
+        }
+        self.view_background = Some(state);
+        self.active_modal = Some(crate::app::ModalKind::ViewBackground);
+    }
+
+    pub(in crate::app) fn update_view_background(
+        &mut self,
+        message: crate::ui::window::pdf_dialogs::PdfDialogMsg,
+    ) -> Task<Message> {
+        use crate::ui::window::pdf_dialogs::{BgKind, BgPosition, PdfDialogMsg as M};
+        use codec::objects::{
+            ClassObjectData as D, GradientBackground, ImageBackground, SolidBackground,
+        };
+        let i = self.active_tab;
+        let Some(state) = self.view_background.as_mut() else {
+            return Task::none();
+        };
+        match message {
+            M::BgKind(kind) => state.kind = kind,
+            M::BgThree(on) => state.three = on,
+            M::BgRotation(value) => state.rotation = value,
+            M::BgImage(value) => state.image = value,
+            M::BgPosition(value) => state.position = value,
+            M::BgAspect(on) => state.aspect = on,
+            M::BgColor(slot, rgb) => match slot {
+                0 => state.solid = rgb,
+                1 => state.top = rgb,
+                2 => state.middle = rgb,
+                _ => state.bottom = rgb,
+            },
+            M::BgPickColor(slot) => {
+                let [r, g, b] = match slot {
+                    0 => state.solid,
+                    1 => state.top,
+                    2 => state.middle,
+                    _ => state.bottom,
+                };
+                return Task::done(Message::OpenColorWindow(
+                    crate::app::ColorPickTarget::ViewBackground(slot),
+                    codec::types::Color::Rgb { r, g, b },
+                ));
+            }
+            M::BgBrowse => {
+                return Task::perform(
+                    async {
+                        crate::sys::file_dialog()
+                            .set_title(crate::tr!("view-background", "select-image"))
+                            .add_filter(
+                                crate::tr!("view-background", "image-files"),
+                                &["png", "jpg", "jpeg", "bmp", "tif", "tiff", "gif", "tga"],
+                            )
+                            .pick_file()
+                            .await
+                            .map(|handle| crate::sys::handle_path(&handle))
+                    },
+                    |path| match path {
+                        Some(path) => Message::PdfDialog(M::BgImage(path.display().to_string())),
+                        None => Message::Noop,
+                    },
+                );
+            }
+            M::BgApply => {
+                // Colours are stored as true colours (flag byte 0xC2), as the
+                // reference stores them.
+                let pack = |c: [u8; 3]| {
+                    0xC200_0000 | (c[0] as u32) << 16 | (c[1] as u32) << 8 | c[2] as u32
+                };
+                let data = match state.kind {
+                    BgKind::None => None,
+                    BgKind::Solid => Some(D::SolidBackground(SolidBackground {
+                        class_version: 1,
+                        color: pack(state.solid),
+                    })),
+                    BgKind::Gradient => {
+                        let Some(rotation) = state
+                            .rotation
+                            .trim()
+                            .parse::<f64>()
+                            .ok()
+                            .filter(|v| v.is_finite())
+                        else {
+                            self.command_line
+                                .push_error(crate::t!("Requires a number.").as_ref());
+                            return Task::none();
+                        };
+                        Some(D::GradientBackground(GradientBackground {
+                            class_version: 1,
+                            color_top: pack(state.top),
+                            color_middle: pack(state.middle),
+                            color_bottom: pack(state.bottom),
+                            horizon: 0.5,
+                            // The reference marks a three-colour gradient by its
+                            // middle band's height.
+                            height: if state.three { 0.33 } else { 0.0 },
+                            rotation,
+                        }))
+                    }
+                    BgKind::Image => {
+                        if !std::path::Path::new(state.image.trim()).is_file() {
+                            self.command_line.push_error("Invalid Background Image File!");
+                            return Task::none();
+                        }
+                        Some(D::ImageBackground(ImageBackground {
+                            class_version: 1,
+                            filename: state.image.trim().to_string(),
+                            fit_to_screen: state.position == BgPosition::Stretch,
+                            maintain_aspect_ratio: state.aspect,
+                            use_tiling: state.position == BgPosition::Tile,
+                            offset: codec::types::Vector2::new(0.0, 0.0),
+                            scale: codec::types::Vector2::new(1.0, 1.0),
+                        }))
+                    }
+                };
+                let name = state.view.clone();
+                self.view_background = None;
+                self.close_active_modal();
+                if self.tabs[i].scene.document.views.get(&name).is_some() {
+                    self.push_undo_snapshot(i, "-VIEW");
+                    let document = &mut self.tabs[i].scene.document;
+                    let handle = data.map_or(Handle::NULL, |data| {
+                        crate::scene::add_background(document, data)
+                    });
+                    if let Some(view) = document.views.get_mut(&name) {
+                        view.background_handle = handle;
+                    }
+                    self.tabs[i].dirty = true;
+                }
+                return self.run_dash_view("SETTINGS", i);
+            }
+            _ => {}
+        }
+        Task::none()
+    }
+}

src/app/control/actions.rs

@@ -103,6 +103,7 @@ pub(super) const NAMES: &[&str] = &[
     #[cfg(not(target_arch = "wasm32"))]
     "external_change_cancel",
     "pdf_dialog_ok",
+    "view_background",
     "pdf_layer_toggle",
     "pc_manager_toggle",
     "pc_manager",
@@ -1786,6 +1787,53 @@ impl OpenCADStudio {
                 })
             }
             "ribbon_dropdown" => Message::ToggleRibbonDropdown(string(req, "value")?.into()),
+            // The -VIEW Background dialog, one field per call: "type=gradient",
+            // "color|top|middle|bottom=r,g,b", "three=1", "rotation=30",
+            // "image=<path>", "position=center|stretch|tile", "aspect=1",
+            // "apply" or "cancel".
+            "view_background" => {
+                use crate::ui::window::pdf_dialogs::{BgKind, BgPosition, PdfDialogMsg as P};
+                if self.active_modal != Some(crate::app::ModalKind::ViewBackground) {
+                    return Err(failure("no_dialog", "The Background dialog is not open"));
+                }
+                let spec = string(req, "value")?;
+                let (key, value) = spec.split_once('=').unwrap_or((spec, ""));
+                let bad = || failure("invalid_value", spec);
+                let rgb = || -> Result<[u8; 3], Value> {
+                    let parts: Vec<u8> = value
+                        .split(',')
+                        .map(|part| part.trim().parse::<u8>())
+                        .collect::<Result<_, _>>()
+                        .map_err(|_| bad())?;
+                    <[u8; 3]>::try_from(parts).map_err(|_| bad())
+                };
+                match key {
+                    "cancel" => Message::CloseModal,
+                    "apply" => Message::PdfDialog(P::BgApply),
+                    "type" => Message::PdfDialog(P::BgKind(match value {
+                        "none" => BgKind::None,
+                        "solid" => BgKind::Solid,
+                        "gradient" => BgKind::Gradient,
+                        "image" => BgKind::Image,
+                        _ => return Err(bad()),
+                    })),
+                    "color" => Message::PdfDialog(P::BgColor(0, rgb()?)),
+                    "top" => Message::PdfDialog(P::BgColor(1, rgb()?)),
+                    "middle" => Message::PdfDialog(P::BgColor(2, rgb()?)),
+                    "bottom" => Message::PdfDialog(P::BgColor(3, rgb()?)),
+                    "three" => Message::PdfDialog(P::BgThree(value == "1")),
+                    "rotation" => Message::PdfDialog(P::BgRotation(value.to_string())),
+                    "image" => Message::PdfDialog(P::BgImage(value.to_string())),
+                    "position" => Message::PdfDialog(P::BgPosition(match value {
+                        "center" => BgPosition::Center,
+                        "stretch" => BgPosition::Stretch,
+                        "tile" => BgPosition::Tile,
+                        _ => return Err(bad()),
+                    })),
+                    "aspect" => Message::PdfDialog(P::BgAspect(value == "1")),
+                    _ => return Err(bad()),
+                }
+            }
             "pdf_dialog_ok" => {
                 use crate::ui::window::pdf_dialogs::PdfDialogMsg;
                 Message::PdfDialog(match self.active_modal {

src/app/mod.rs

@@ -502,6 +502,8 @@ pub(super) struct OpenCADStudio {
     field_dialog: Option<crate::ui::window::field_dialog::FieldDialogState>,
     point_cloud_color_map: Option<crate::ui::window::pdf_dialogs::PointCloudColorMapState>,
     pc_section: Option<crate::ui::window::pdf_dialogs::PcSectionState>,
+    /// -VIEW sEttings Background dialog.
+    view_background: Option<crate::ui::window::pdf_dialogs::ViewBackgroundState>,
     underlay_layers: Option<crate::ui::window::pdf_dialogs::UnderlayLayersState>,
     pdf_import_settings: Option<crate::modules::insert::pdf_import::PdfImportSettings>,
     pdf_import_file: Option<crate::ui::window::pdf_dialogs::PdfImportFileState>,
@@ -1641,6 +1643,8 @@ pub enum ColorPickTarget {
     LayerState(usize),
     /// The MText editor's selection (or global) colour.
     MText,
+    /// A colour of the view Background dialog: 0 solid, 1 top, 2 middle, 3 bottom.
+    ViewBackground(u8),
 }
 
 /// Table records the clipboard entities depend on, snapshotted from the source
@@ -1981,6 +1985,7 @@ pub enum ModalKind {
     PointCloudAttach,
     PointCloudColorMap,
     PcSection,
+    ViewBackground,
     UnderlayLayers,
     PdfImportSettings,
     PdfImportFile,
@@ -4186,6 +4191,7 @@ impl OpenCADStudio {
             field_dialog: None,
             point_cloud_color_map: None,
             pc_section: None,
+            view_background: None,
             underlay_layers: None,
             pdf_import_settings: None,
             pdf_import_file: None,

src/app/update/mod.rs

@@ -8799,6 +8799,13 @@ impl OpenCADStudio {
                     self.close_sheet_set_dialog();
                     return Task::none();
                 }
+                // The Background dialog returns to -VIEW's settings prompt.
+                if self.active_modal == Some(super::ModalKind::ViewBackground) {
+                    self.view_background = None;
+                    self.close_active_modal();
+                    let i = self.active_tab;
+                    return self.run_dash_view("SETTINGS", i);
+                }
                 if self.active_modal == Some(super::ModalKind::Field) {
                     self.close_field_dialog();
                     return Task::none();

src/app/update/style.rs

@@ -1162,6 +1162,18 @@ impl OpenCADStudio {
                     crate::ui::window::gradient_editor::GradientMsg::Color(index, color),
                 )))
             }
+            Some(crate::app::ColorPickTarget::ViewBackground(slot)) => {
+                let rgb = match color {
+                    codec::types::Color::Rgb { r, g, b } => Some([r, g, b]),
+                    codec::types::Color::Index(index) => {
+                        codec::types::aci_table::aci_to_rgb(index).map(|(r, g, b)| [r, g, b])
+                    }
+                    _ => None,
+                };
+                rgb.map(|rgb| {
+                    Message::PdfDialog(crate::ui::window::pdf_dialogs::PdfDialogMsg::BgColor(slot, rgb))
+                })
+            }
             Some(crate::app::ColorPickTarget::GraphicAttributesLine) => Some(
                 Message::GraphicAttributes(GraphicAttributesMsg::LineColor(color)),
             ),

src/app/view/modal.rs

@@ -35,6 +35,11 @@ impl OpenCADStudio {
             Some(K::PointCloudAttach) => crate::t!("Attach Point Cloud").into_owned(),
             Some(K::PointCloudColorMap) => crate::t!("Point Cloud Color Map").into_owned(),
             Some(K::PcSection) => crate::t!("Extract Section Lines from Point Cloud").into_owned(),
+            Some(K::ViewBackground) => format!(
+                "{} — {}",
+                crate::tr!("view-background", "title"),
+                self.view_background.as_ref().map_or("", |s| s.view.as_str())
+            ),
             Some(K::UnderlayLayers) => crate::t!("Underlay Layers").into_owned(),
             Some(K::PdfImportSettings) => crate::t!("PDF Import Settings").into_owned(),
             Some(K::PdfImportFile) => crate::t!("Import PDF").into_owned(),
@@ -510,6 +515,12 @@ impl OpenCADStudio {
                     crate::ui::window::pdf_dialogs::view_pc_section(state, flow)
                 })
             }
+            super::super::ModalKind::ViewBackground => {
+                let state = self.view_background.as_ref()?;
+                sized_flow(ex, 420, 560, |flow| {
+                    crate::ui::window::pdf_dialogs::view_background(state, flow)
+                })
+            }
             super::super::ModalKind::UnderlayLayers => {
                 let state = self.underlay_layers.as_ref()?;
                 sized_flow(ex, 460, 520, |flow| {