KCL python: add required classes to module (#7928)

adamchalmers · web-flow · commit 7ce6320923ae · 2025-07-30T09:30:33.000-05:00
- The function I added required a parameter of type SnapshotOptions but I didn't make that type available through our module
- Ensure that you can set SnapshotOptions in both the "execute this KCL string" function and the "execute this KCL file path" function.
- Unit test
diff --git a/rust/kcl-python-bindings/justfile b/rust/kcl-python-bindings/justfile
@@ -1,8 +1,19 @@
 test:
     uv pip install .[test]
     uv run pytest tests/tests.py
+
+test-filter name:
+    uv pip install .[test]
+    uv run pytest tests/tests.py::{{name}}
+
 setup-uv:
     uv python install
     uv venv .venv
     echo "VIRTUAL_ENV=.venv" >> $GITHUB_ENV
     echo "$PWD/.venv/bin" >> $GITHUB_PATH
+
+lint:
+    uv run ruff check
+
+fmt:
+    uv run ruff format
diff --git a/rust/kcl-python-bindings/src/bridge.rs b/rust/kcl-python-bindings/src/bridge.rs
@@ -1,22 +1,40 @@
 //! For creating equivalents to the core kcmc types that support Python.
 use kittycad_modeling_cmds as kcmc;
-use pyo3::pyclass;
+use pyo3::{pyclass, pymethods};
 use serde::{Deserialize, Serialize};
 
-#[derive(Serialize, Deserialize, PartialEq, Debug, Clone)]
+#[derive(Serialize, Deserialize, PartialEq, Debug, Clone, Copy)]
 #[pyclass]
 pub struct Point3d {
-    x: f32,
-    y: f32,
-    z: f32,
+    pub x: f32,
+    pub y: f32,
+    pub z: f32,
 }
 
-#[derive(Serialize, Deserialize, PartialEq, Debug, Clone)]
+#[pymethods]
+impl Point3d {
+    #[new]
+    /// Create a new point from its 3 components x, y and z
+    /// All of them take floating point values.
+    fn new(x: f32, y: f32, z: f32) -> Self {
+        Self { x, y, z }
+    }
+}
+
+#[derive(Serialize, Deserialize, PartialEq, Debug, Clone, Copy)]
 #[pyclass]
 pub struct CameraLookAt {
-    vantage: Point3d,
-    center: Point3d,
-    up: Point3d,
+    pub vantage: Point3d,
+    pub center: Point3d,
+    pub up: Point3d,
+}
+
+#[pymethods]
+impl CameraLookAt {
+    #[new]
+    fn new(vantage: Point3d, center: Point3d, up: Point3d) -> Self {
+        Self { vantage, center, up }
+    }
 }
 
 impl From<CameraLookAt> for kcmc::DefaultCameraLookAt {
diff --git a/rust/kcl-python-bindings/src/lib.rs b/rust/kcl-python-bindings/src/lib.rs
@@ -359,6 +359,16 @@ async fn mock_execute(path: String) -> PyResult<bool> {
 /// Execute a kcl file and snapshot it in a specific format.
 #[pyfunction]
 async fn execute_and_snapshot(path: String, image_format: ImageFormat) -> PyResult<Vec<u8>> {
+    let img = execute_and_snapshot_views(path, image_format, Vec::new()).await?.pop();
+    Ok(img.unwrap())
+}
+
+#[pyfunction]
+async fn execute_and_snapshot_views(
+    path: String,
+    image_format: ImageFormat,
+    snapshot_options: Vec<SnapshotOptions>,
+) -> PyResult<Vec<Vec<u8>>> {
     tokio()
         .spawn(async move {
             let (code, path) = get_code_and_file_path(&path)
@@ -375,41 +385,7 @@ async fn execute_and_snapshot(path: String, image_format: ImageFormat) -> PyResu
                 .await
                 .map_err(|err| into_miette(err, &code))?;
 
-            // Zoom to fit.
-            ctx.engine
-                .send_modeling_cmd(
-                    uuid::Uuid::new_v4(),
-                    kcl_lib::SourceRange::default(),
-                    &kittycad_modeling_cmds::ModelingCmd::ZoomToFit(kittycad_modeling_cmds::ZoomToFit {
-                        object_ids: Default::default(),
-                        padding: 0.1,
-                        animated: false,
-                    }),
-                )
-                .await?;
-
-            // Send a snapshot request to the engine.
-            let resp = ctx
-                .engine
-                .send_modeling_cmd(
-                    uuid::Uuid::new_v4(),
-                    kcl_lib::SourceRange::default(),
-                    &kittycad_modeling_cmds::ModelingCmd::TakeSnapshot(kittycad_modeling_cmds::TakeSnapshot {
-                        format: image_format.into(),
-                    }),
-                )
-                .await?;
-
-            let kittycad_modeling_cmds::websocket::OkWebSocketResponseData::Modeling {
-                modeling_response: kittycad_modeling_cmds::ok_response::OkModelingCmdResponse::TakeSnapshot(data),
-            } = resp
-            else {
-                return Err(pyo3::exceptions::PyException::new_err(format!(
-                    "Unexpected response from engine: {resp:?}"
-                )));
-            };
-
-            Ok(data.contents.0)
+            take_snaps(&ctx, image_format, snapshot_options).await
         })
         .await
         .map_err(|err| pyo3::exceptions::PyException::new_err(err.to_string()))?
@@ -418,23 +394,43 @@ async fn execute_and_snapshot(path: String, image_format: ImageFormat) -> PyResu
 /// Execute the kcl code and snapshot it in a specific format.
 #[pyfunction]
 async fn execute_code_and_snapshot(code: String, image_format: ImageFormat) -> PyResult<Vec<u8>> {
-    let mut snaps = execute_code_and_snapshot_at_views(code, image_format, Vec::new()).await?;
+    let mut snaps = execute_code_and_snapshot_views(code, image_format, Vec::new()).await?;
     Ok(snaps.pop().unwrap())
 }
 
+/// Customize a snapshot.
 #[derive(Serialize, Deserialize, PartialEq, Debug, Clone)]
 #[pyclass]
-struct SnapshotOptions {
+pub struct SnapshotOptions {
     /// If none, will use isometric view.
-    camera: Option<bridge::CameraLookAt>,
-    padding: f32,
+    pub camera: Option<bridge::CameraLookAt>,
+    /// How much to pad the view frame by, as a fraction of the object(s) bounding box size.
+    /// Negative padding will crop the view of the object proportionally.
+    /// e.g. padding = 0.2 means the view will span 120% of the object(s) bounding box,
+    /// and padding = -0.2 means the view will span 80% of the object(s) bounding box.
+    pub padding: f32,
+}
+
+#[pymethods]
+impl SnapshotOptions {
+    #[new]
+    /// Takes a kcl.CameraLookAt, and a padding number.
+    fn new(camera: Option<bridge::CameraLookAt>, padding: f32) -> Self {
+        Self { camera, padding }
+    }
+
+    #[staticmethod]
+    /// Takes a padding number.
+    fn isometric_view(padding: f32) -> Self {
+        Self::new(None, padding)
+    }
 }
 
 /// Execute the kcl code and snapshot it in a specific format.
 /// Returns one image for each camera angle you provide.
 /// If you don't provide any camera angles, a default head-on camera angle will be used.
 #[pyfunction]
-async fn execute_code_and_snapshot_at_views(
+async fn execute_code_and_snapshot_views(
     code: String,
     image_format: ImageFormat,
     snapshot_options: Vec<SnapshotOptions>,
@@ -452,34 +448,42 @@ async fn execute_code_and_snapshot_at_views(
                 .await
                 .map_err(|err| into_miette(err, &code))?;
 
-            if snapshot_options.is_empty() {
-                let data_bytes = snapshot(&ctx, image_format, 0.1).await?;
-                return Ok(vec![data_bytes]);
-            }
-
-            let mut snaps = Vec::with_capacity(snapshot_options.len());
-            for pre_snap in snapshot_options {
-                if let Some(camera) = pre_snap.camera {
-                    let view_cmd = kcmc::DefaultCameraLookAt::from(camera);
-                    let view_cmd = kcmc::ModelingCmd::DefaultCameraLookAt(view_cmd);
-                    ctx.engine
-                        .send_modeling_cmd(uuid::Uuid::new_v4(), Default::default(), &view_cmd)
-                        .await?;
-                } else {
-                    let view_cmd = kcmc::ModelingCmd::ViewIsometric(kcmc::ViewIsometric { padding: 0.0 });
-                    ctx.engine
-                        .send_modeling_cmd(uuid::Uuid::new_v4(), Default::default(), &view_cmd)
-                        .await?;
-                }
-                let data_bytes = snapshot(&ctx, image_format, pre_snap.padding).await?;
-                snaps.push(data_bytes);
-            }
-            Ok(snaps)
+            take_snaps(&ctx, image_format, snapshot_options).await
         })
         .await
         .map_err(|err| pyo3::exceptions::PyException::new_err(err.to_string()))?
 }
 
+async fn take_snaps(
+    ctx: &ExecutorContext,
+    image_format: ImageFormat,
+    snapshot_options: Vec<SnapshotOptions>,
+) -> PyResult<Vec<Vec<u8>>> {
+    if snapshot_options.is_empty() {
+        let data_bytes = snapshot(ctx, image_format, 0.1).await?;
+        return Ok(vec![data_bytes]);
+    }
+
+    let mut snaps = Vec::with_capacity(snapshot_options.len());
+    for pre_snap in snapshot_options {
+        if let Some(camera) = pre_snap.camera {
+            let view_cmd = kcmc::DefaultCameraLookAt::from(camera);
+            let view_cmd = kcmc::ModelingCmd::DefaultCameraLookAt(view_cmd);
+            ctx.engine
+                .send_modeling_cmd(uuid::Uuid::new_v4(), Default::default(), &view_cmd)
+                .await?;
+        } else {
+            let view_cmd = kcmc::ModelingCmd::ViewIsometric(kcmc::ViewIsometric { padding: 0.0 });
+            ctx.engine
+                .send_modeling_cmd(uuid::Uuid::new_v4(), Default::default(), &view_cmd)
+                .await?;
+        }
+        let data_bytes = snapshot(ctx, image_format, pre_snap.padding).await?;
+        snaps.push(data_bytes);
+    }
+    Ok(snaps)
+}
+
 async fn snapshot(ctx: &ExecutorContext, image_format: ImageFormat, padding: f32) -> PyResult<Vec<u8>> {
     // Zoom to fit.
     ctx.engine
@@ -657,6 +661,9 @@ fn kcl(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<FileExportFormat>()?;
     m.add_class::<UnitLength>()?;
     m.add_class::<Discovered>()?;
+    m.add_class::<SnapshotOptions>()?;
+    m.add_class::<bridge::Point3d>()?;
+    m.add_class::<bridge::CameraLookAt>()?;
 
     // Add our functions to the module.
     m.add_function(wrap_pyfunction!(parse, m)?)?;
@@ -666,8 +673,9 @@ fn kcl(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(mock_execute, m)?)?;
     m.add_function(wrap_pyfunction!(mock_execute_code, m)?)?;
     m.add_function(wrap_pyfunction!(execute_and_snapshot, m)?)?;
+    m.add_function(wrap_pyfunction!(execute_and_snapshot_views, m)?)?;
     m.add_function(wrap_pyfunction!(execute_code_and_snapshot, m)?)?;
-    m.add_function(wrap_pyfunction!(execute_code_and_snapshot_at_views, m)?)?;
+    m.add_function(wrap_pyfunction!(execute_code_and_snapshot_views, m)?)?;
     m.add_function(wrap_pyfunction!(execute_and_export, m)?)?;
     m.add_function(wrap_pyfunction!(execute_code_and_export, m)?)?;
     m.add_function(wrap_pyfunction!(format, m)?)?;
diff --git a/rust/kcl-python-bindings/tests/tests.py b/rust/kcl-python-bindings/tests/tests.py
@@ -2,6 +2,7 @@
 import os
 
 import kcl
+from kcl import Point3d
 import pytest
 
 # Get the path to this script's parent directory.
@@ -174,6 +175,31 @@ async def test_kcl_execute_and_snapshot():
     assert len(image_bytes) > 0
 
 
+@pytest.mark.asyncio
+async def test_kcl_execute_and_snapshot_options():
+    camera = kcl.CameraLookAt(
+        # Test both constructors, with unnamed fields and named fields.
+        up=Point3d(0, 0, 1),
+        vantage=Point3d(x=0, y=-1, z=0),
+        center=Point3d(x=0, y=0, z=0),
+    )
+    views = [
+        # Specific camera perspective
+        kcl.SnapshotOptions(camera=camera, padding=0.5),
+        # Camera=None means isometric view.
+        kcl.SnapshotOptions(camera=None, padding=0),
+    ]
+    # Read from a file.
+    images = await kcl.execute_and_snapshot_views(
+        lego_file, kcl.ImageFormat.Jpeg, views
+    )
+    assert images is not None
+    assert len(images) == len(views)
+    image_bytes = images[0]
+    assert image_bytes is not None
+    assert len(image_bytes) > 0
+
+
 @pytest.mark.asyncio
 async def test_kcl_execute_and_snapshot_dir():
     # Read from a file.
