Complete Ole2Frame: embed a picture file from a script

EmbedPicture builds the frame with OCS's own EmbeddedImage and
build_embedded_ole, so the opaque storage is never scripted. PNG, JPEG and
BMP are stored as read and other formats are re-encoded as PNG. The lifecycle
test now creates through Python; a new test covers formats, aspect, origin,
layer and refusals.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

plugins/opencad-python/entity_manifest.json

@@ -789,7 +789,7 @@
     },
     "Ole2Frame": {
       "update_only": true,
-      "update_only_message": "Ole2Frame cannot be created from a script: its embedded object storage is opaque; existing frames can be moved, resized and aspect-locked, and the stored object is preserved untouched",
+      "update_only_message": "create an Ole2Frame with doc.embed_picture(path, origin, width); existing frames can be moved, resized and aspect-locked, and the stored object is preserved untouched",
       "fields": {
         "storage": {
           "exclude": true,

plugins/opencad-python/src/document_model.py

@@ -220,6 +220,13 @@ class _Document:
         handle = entity.handle if isinstance(entity, _Entity) else int(entity)
         ocs.remove_entity(handle)
 
+    def embed_picture(self, path, origin=(0, 0, 0), width=1, layer=None):
+        """Embed a picture file (PNG, JPEG, BMP or another format re-encoded as
+        PNG) as an OLE frame. `origin` is the bottom-left corner and `width`
+        the frame width; the height follows the picture's aspect ratio."""
+        handle = ocs.embed_picture(str(path), [float(v) for v in origin], float(width), layer)
+        return self.entities[handle]
+
     def coverage(self, kind=None):
         if kind is not None:
             return ocs.entity_coverage(kind)

plugins/opencad-python/src/ocs_module.rs

@@ -475,6 +475,28 @@ mod ocs {
             .map_err(|error| vm.new_runtime_error(format!("ocs.solid_region: {error}")))
     }
 
+    /// Embed a picture file as an OLE frame.
+    #[pyfunction]
+    fn embed_picture(
+        path: String,
+        origin: Vec<f64>,
+        width: f64,
+        layer: Option<String>,
+        vm: &VirtualMachine,
+    ) -> PyResult<u64> {
+        use ocs_plugin_api::host::SolidOperation;
+        let origin: [f64; 3] = origin.try_into().map_err(|_| {
+            vm.new_value_error("ocs.embed_picture: the origin needs 3 numbers".to_owned())
+        })?;
+        let result = host_ctx::with_host(|host| {
+            host.solid_operation(SolidOperation::EmbedPicture { path, origin, width, layer })
+        })
+        .ok_or_else(|| vm.new_runtime_error("ocs: not running inside a PY_ command".to_owned()))?;
+        result
+            .map(|handle| handle.value())
+            .map_err(|error| vm.new_runtime_error(format!("ocs.embed_picture: {error}")))
+    }
+
     /// Combine two solids ("union", "subtract" or "intersect").
     #[pyfunction]
     fn solid_boolean(