feat: add QR code generation, animation, and UI improvements

Add QR code generation to 3MF files.
Add animation support for 3MF generation.
Reorganize UI into tabs for front, back, base, settings.
Refactor overlay logic and add helper functions.
Update Dockerfile with a new command and copy examples.
Update requirements with new dependencies and updated versions.
Add example images to repository.

Dockerfile

@@ -11,15 +11,16 @@ RUN apt-get update \
 
 FROM base AS developer
 
-ENV GRADIO_WATCH_DIRS="/app/src"
+ENV GRADIO_ANALYTICS_ENABLED=False
 
-CMD ["python3", "src/app.py"]
+CMD ["sh", "-c", "cd src; gradio app.py"]
 
 
 FROM base AS executor
 
 WORKDIR /app
 
-COPY src/app.py src/3mf2mmuv3.py src/input.scad.j2 src/png23mf.py /app/
+COPY src /app/src
+COPY examples /app/examples
 
-CMD ["python3", "app.py"]
+CMD ["python3", "src/app.py"]

requirements.txt

@@ -1,4 +1,5 @@
-gradio==6.9.0
-ruff==0.15.6
+gradio==6.10.0
+ruff==0.15.8
 scipy==1.17.1
 jinja2==3.1.6
+qrcode==8.2

src/.gitignore

@@ -1 +0,0 @@
-tmp/

src/animate.scad.j2

@@ -0,0 +1 @@
+rotate([0,$t*360,0]) import("{{ model_path }}", center=true);

src/app.py

@@ -1,53 +1,180 @@
 #!/usr/bin/env python3
 
+import logging
 import shutil
 import tempfile
+from functools import partial
 from pathlib import Path
 
 import gradio as gr
 
 from png23mf import (
-    calculate_zoom_value,
+    flip_image_horizontally,
     generate_3mf_file,
+    generate_qrcode,
     overlay_images_core,
-    update_height_from_width,
-    update_width_from_height,
 )
 
+logger = logging.getLogger(__name__)
+
 temp_dir = Path(tempfile.gettempdir())
 
 
-def overlay_images(
+def calculate_zoom_value(
+    *,
     base_img,
     overlay_img,
+    current_zoom,
+    resolution,
+):
+    """Calculate zoom to fit overlay on base image."""
+    logger.debug(f"Entering calculate_zoom_value with arguments: {locals()}")
+    if base_img is None or overlay_img is None:
+        result = current_zoom
+        logger.debug(f"Exiting calculate_zoom_value with result: {result!r}")
+        return result
+    base = base_img.convert(mode="RGBA")
+    w_base, h_base = base.size
+    if max(w_base, h_base) > resolution:
+        scale_factor = resolution / max(w_base, h_base)
+        w_base = int(w_base * scale_factor)
+        h_base = int(h_base * scale_factor)
+    base_longer = max(w_base, h_base)
+    w_overlay, h_overlay = overlay_img.size
+    overlay_longer = max(w_overlay, h_overlay)
+    if overlay_longer > base_longer:
+        zoom = round(base_longer / overlay_longer, 2)
+        zoom = max(0.01, min(10.0, zoom))
+        result = zoom
+        logger.debug(f"Exiting calculate_zoom_value with result: {result!r}")
+        return result
+    else:
+        result = current_zoom
+        logger.debug(f"Exiting calculate_zoom_value with result: {result!r}")
+        return result
+
+
+def update_width_from_height(
+    height, width, use_aspect_ratio, base_img, overlay_img
+):
+    """Calculate new width based on height and aspect ratio."""
+    logger.debug(
+        f"Entering update_width_from_height with arguments: {locals()}"
+    )
+    if use_aspect_ratio:
+        if base_img is not None:
+            w_base, h_base = base_img.size
+        elif overlay_img is not None:
+            w_base, h_base = overlay_img.size
+        else:
+            result = width
+            logger.debug(
+                f"Exiting update_width_from_height with result: {result!r}"
+            )
+            return result
+        new_width = round(height * w_base / h_base, 2)
+        if abs(new_width - width) > 1e-6:
+            result = new_width
+            logger.debug(
+                f"Exiting update_width_from_height with result: {result!r}"
+            )
+            return result
+    result = width
+    logger.debug(f"Exiting update_width_from_height with result: {result!r}")
+
+    return result
+
+
+def update_height_from_width(
+    width, height, use_aspect_ratio, base_img, overlay_img
+):
+    """Calculate new height based on width and aspect ratio."""
+    logger.debug(
+        f"Entering update_height_from_width with arguments: {locals()}"
+    )
+    if use_aspect_ratio:
+        if base_img is not None:
+            w_base, h_base = base_img.size
+        elif overlay_img is not None:
+            w_base, h_base = overlay_img.size
+        else:
+            result = height
+            logger.debug(
+                f"Exiting update_height_from_width with result: {result!r}"
+            )
+            return result
+        new_height = round(width * h_base / w_base, 2)
+        if abs(new_height - height) > 1e-6:
+            result = new_height
+            logger.debug(
+                f"Exiting update_height_from_width with result: {result!r}"
+            )
+            return result
+    result = height
+    logger.debug(f"Exiting update_height_from_width with result: {result!r}")
+
+    return result
+
+
+def overlay_front_images(
+    base_img,
+    front_img,
+    x,
+    y,
+    rot,
+    zoom,
+    indexed_colors,
+    use_common_colors,
+    morph_size,
+    resolution,
+):
+    """Overlay an image onto a base image and extract masks."""
+    base_rgb, masks, mask_colors = overlay_images_core(
+        base_img=base_img,
+        overlay_img=front_img,
+        x=x,
+        y=y,
+        rot=rot,
+        zoom=zoom,
+        indexed_colors=indexed_colors,
+        use_common_colors=use_common_colors,
+        morph_size=morph_size,
+        resolution=resolution,
+    )
+    if base_rgb is None:
+        return None, None, None, None, gr.update(interactive=False)
+    return base_rgb, masks, masks, mask_colors, gr.update(interactive=True)
+
+
+def overlay_back_images(
+    base_img,
+    back_img,
     x,
     y,
     rot,
     zoom,
     indexed_colors,
-    base_thickness,
-    overlay_thickness,
-    width,
-    height,
     use_common_colors,
     morph_size,
     resolution,
 ):
+    """Overlay an image onto a base image and extract masks."""
+    flipped_base_img = (
+        flip_image_horizontally(image=base_img)
+        if base_img is not None
+        else None
+    )
     base_rgb, masks, mask_colors = overlay_images_core(
-        base_img,
-        overlay_img,
-        x,
-        y,
-        rot,
-        zoom,
-        indexed_colors,
-        base_thickness,
-        overlay_thickness,
-        width,
-        height,
-        use_common_colors,
-        morph_size,
-        resolution,
+        base_img=flipped_base_img,
+        overlay_img=back_img,
+        x=x,
+        y=y,
+        rot=rot,
+        zoom=zoom,
+        indexed_colors=indexed_colors,
+        use_common_colors=use_common_colors,
+        morph_size=morph_size,
+        resolution=resolution,
     )
     if base_rgb is None:
         return None, None, None, None, gr.update(interactive=False)
@@ -70,7 +197,12 @@ def update_slider_ranges(base_img, overlay_img, resolution):
     default_width = round(100, 2)
     default_height = round(default_width * h / w, 2)
     if overlay_img is not None:
-        zoom_val = calculate_zoom_value(base_img, overlay_img, 1.0, resolution)
+        zoom_val = calculate_zoom_value(
+            base_img=base_img,
+            overlay_img=overlay_img,
+            current_zoom=1.0,
+            resolution=resolution,
+        )
     else:
         zoom_val = 1.0
     return (
@@ -85,7 +217,6 @@ def update_slider_ranges(base_img, overlay_img, resolution):
 
 
 def get_user_dir(req: gr.Request) -> str:
-    """Create a unique directory for the user session."""
     session_hash = (
         str(req.session_hash) if req.session_hash is not None else "unknown"
     )
@@ -95,7 +226,6 @@ def get_user_dir(req: gr.Request) -> str:
 
 
 def delete_user_dir(req: gr.Request) -> None:
-    """Delete the user directory when the session ends."""
     session_hash = (
         str(req.session_hash) if req.session_hash is not None else "unknown"
     )
@@ -104,206 +234,358 @@ def delete_user_dir(req: gr.Request) -> None:
         shutil.rmtree(user_dir)
 
 
+def switch_to_model_tab():
+    return gr.update(selected="model")
+
+
+generate_3mf_with_frames = partial(generate_3mf_file, animate_frames=18)
+
+
+def generate_qr_code_from_text(text: str):
+    """Generate a QR code image from input text."""
+    logger.debug(
+        f"Entering generate_qr_code_from_text with arguments: {locals()}"
+    )
+    image = generate_qrcode(fill_color="random", text=text)
+    result = image
+    logger.debug(f"Exiting generate_qrcode with result: {result!r}")
+
+    return result
+
+
 with gr.Blocks() as demo:
     gr.Markdown(value="# PNG to scad/3mf")
-    gr.Markdown(
-        value="**Tip:** The base image must be black and white. "
-        "Black is treated as transparent and White will be extruded."
-    )
+
     with gr.Row():
         with gr.Column():
-            with gr.Row():
-                base_img = gr.Image(
-                    label="Base Image",
-                    type="pil",
-                    image_mode="RGB",
-                )
-                overlay_img = gr.Image(
-                    label="Overlay Image",
-                    type="pil",
-                    image_mode="RGBA",
-                )
-            with gr.Column():
-                x_slider = gr.Slider(
-                    label="X (px)",
-                    minimum=-500,
-                    maximum=500,
-                    step=1,
-                    value=0,
-                    interactive=False,
-                    info="Overlay image X coordinate relative to base",
-                )
-                y_slider = gr.Slider(
-                    label="Y (px)",
-                    minimum=-500,
-                    maximum=500,
-                    step=1,
-                    value=0,
-                    interactive=False,
-                    info="Overlay image Y coordinate relative to base",
-                )
-                rot_slider = gr.Slider(
-                    label="Rotation (°)",
-                    minimum=-180,
-                    maximum=180,
-                    step=1,
-                    value=0,
-                    interactive=False,
-                    info="Rotate overlay image",
-                )
-                zoom_slider = gr.Slider(
-                    label="Zoom",
-                    minimum=0.01,
-                    maximum=10.0,
-                    step=0.01,
-                    value=1.0,
-                    interactive=False,
-                    info="Make overlay image bigger or smaller",
-                )
-                indexed_slider = gr.Slider(
-                    label="Indexed Colors",
-                    minimum=2,
-                    maximum=255,
-                    step=1,
-                    value=4,
-                    info="Overlay image colors will be quantized",
-                )
-                use_common_colors_checkbox = gr.Checkbox(
-                    label="Use most common colors for quantization",
-                    value=True,
-                    interactive=True,
-                    info="Best for the logo's.",
-                )
-                morphology_slider = gr.Slider(
-                    label="Morphology Size",
-                    minimum=1,
-                    maximum=20,
-                    step=1,
-                    value=1,
-                    info=(
-                        "Size of morphological opening/closing "
-                        "to remove small features"
-                    ),
-                )
-                resolution_dropdown = gr.Dropdown(
-                    label="Resolution (px)",
-                    choices=[512, 1024, 2048],
-                    value=512,
-                    interactive=True,
-                )
+            with gr.Tabs() as left_tabs:
+                with gr.Tab("Front Image"):
+                    with gr.Row():
+                        front_overlay_img = gr.Image(
+                            label="Front Image",
+                            type="pil",
+                            image_mode="RGBA",
+                        )
+                    with gr.Row():
+                        qr_text_front = gr.Textbox(
+                            label="Generate QR-code",
+                            placeholder="Enter text",
+                            submit_btn = "▣ QRCode"
+                        )
+                    with gr.Column():
+                        x_slider = gr.Slider(
+                            label="X (px)",
+                            minimum=-500,
+                            maximum=500,
+                            step=1,
+                            value=0,
+                            interactive=False,
+                            info="Overlay image X coordinate relative to base",
+                        )
+                        y_slider = gr.Slider(
+                            label="Y (px)",
+                            minimum=-500,
+                            maximum=500,
+                            step=1,
+                            value=0,
+                            interactive=False,
+                            info="Overlay image Y coordinate relative to base",
+                        )
+                        rot_slider = gr.Slider(
+                            label="Rotation (°)",
+                            minimum=-180,
+                            maximum=180,
+                            step=1,
+                            value=0,
+                            interactive=False,
+                            info="Rotate overlay image",
+                        )
+                        zoom_slider = gr.Slider(
+                            label="Zoom",
+                            minimum=0.01,
+                            maximum=10.0,
+                            step=0.01,
+                            value=1.0,
+                            interactive=False,
+                            info="Make overlay image bigger or smaller",
+                        )
+                        indexed_slider = gr.Slider(
+                            label="Indexed Colors",
+                            minimum=2,
+                            maximum=255,
+                            step=1,
+                            value=4,
+                            info="Overlay image colors will be quantized",
+                        )
+                        use_common_colors_checkbox = gr.Checkbox(
+                            label="Use most common colors for quantization",
+                            value=True,
+                            interactive=True,
+                            info="Best for the logo's.",
+                        )
+                        morphology_slider = gr.Slider(
+                            label="Morphology Size",
+                            minimum=1,
+                            maximum=20,
+                            step=1,
+                            value=1,
+                            info=(
+                                "Size of morphological opening/closing "
+                                "to remove small features"
+                            ),
+                        )
+                with gr.Tab("Back Image"):
+                    with gr.Row():
+                        back_overlay_img = gr.Image(
+                            label="Back Image",
+                            type="pil",
+                            image_mode="RGBA",
+                        )
+                    with gr.Row():
+                        qr_text_back = gr.Textbox(
+                            label="Generate QR-code",
+                            placeholder="Enter text",
+                            submit_btn = "▣ QRCode"
+                        )
+                    with gr.Column():
+                        x_slider_back = gr.Slider(
+                            label="X (px)",
+                            minimum=-500,
+                            maximum=500,
+                            step=1,
+                            value=0,
+                            interactive=False,
+                            info="Overlay image X coordinate relative to base",
+                        )
+                        y_slider_back = gr.Slider(
+                            label="Y (px)",
+                            minimum=-500,
+                            maximum=500,
+                            step=1,
+                            value=0,
+                            interactive=False,
+                            info="Overlay image Y coordinate relative to base",
+                        )
+                        rot_slider_back = gr.Slider(
+                            label="Rotation (°)",
+                            minimum=-180,
+                            maximum=180,
+                            step=1,
+                            value=0,
+                            interactive=False,
+                            info="Rotate overlay image",
+                        )
+                        zoom_slider_back = gr.Slider(
+                            label="Zoom",
+                            minimum=0.01,
+                            maximum=10.0,
+                            step=0.01,
+                            value=1.0,
+                            interactive=False,
+                            info="Make overlay image bigger or smaller",
+                        )
+                        indexed_slider_back = gr.Slider(
+                            label="Indexed Colors",
+                            minimum=2,
+                            maximum=255,
+                            step=1,
+                            value=4,
+                            info="Overlay image colors will be quantized",
+                        )
+                        use_common_colors_checkbox_back = gr.Checkbox(
+                            label="Use most common colors for quantization",
+                            value=True,
+                            interactive=True,
+                            info="Best for the logo's.",
+                        )
+                        morphology_slider_back = gr.Slider(
+                            label="Morphology Size",
+                            minimum=1,
+                            maximum=20,
+                            step=1,
+                            value=1,
+                            info=(
+                                "Size of morphological opening/closing "
+                                "to remove small features"
+                            ),
+                        )
+                with gr.Tab("Base Image"):
+                    gr.Markdown(
+                        value="**Tip:** The base image must be "
+                        "black and white. Black is treated as transparent"
+                        "and White will be extruded."
+                    )
+                    with gr.Row():
+                        base_img = gr.Image(
+                            label="Base Image",
+                            type="pil",
+                            image_mode="RGB",
+                        )
+                    gr.Markdown(value="**Examples**")
+                    base_examples_dir = (
+                        Path(__file__).parent.parent / "examples" / "base"
+                    )
+                    gr.Examples(
+                        examples=str(base_examples_dir),
+                        inputs=[base_img],
+                        label="Base",
+                    )
+                    front_examples_dir = (
+                        Path(__file__).parent.parent / "examples" / "front"
+                    )
+                    gr.Examples(
+                        examples=str(front_examples_dir),
+                        inputs=[front_overlay_img],
+                        label="Front",
+                    )
+                    back_examples_dir = (
+                        Path(__file__).parent.parent / "examples" / "back"
+                    )
+                    gr.Examples(
+                        examples=str(back_examples_dir),
+                        inputs=[back_overlay_img],
+                        label="Back",
+                    )
+                with gr.Tab("Settings"):
+                    with gr.Column():
+                        resolution_dropdown = gr.Dropdown(
+                            label="Resolution (px)",
+                            choices=[512, 1024, 2048],
+                            value=512,
+                            interactive=True,
+                        )
+                        width_slider = gr.Number(
+                            label="Width (mm)",
+                            minimum=0,
+                            step=0.01,
+                            value=100,
+                            interactive=True,
+                        )
+                        height_slider = gr.Number(
+                            label="Height (mm)",
+                            minimum=0,
+                            step=0.01,
+                            value=100,
+                            interactive=True,
+                        )
+                        use_aspect_ratio = gr.Checkbox(
+                            label="Use image aspect ratio (base/overlay)",
+                            value=True,
+                            interactive=True,
+                        )
+                        height_slider.input(
+                            fn=update_height_from_width,
+                            inputs=[
+                                height_slider,
+                                width_slider,
+                                use_aspect_ratio,
+                                base_img,
+                                front_overlay_img,
+                            ],
+                            outputs=[width_slider],
+                        )
+                        width_slider.input(
+                            fn=update_width_from_height,
+                            inputs=[
+                                width_slider,
+                                height_slider,
+                                use_aspect_ratio,
+                                base_img,
+                                front_overlay_img,
+                            ],
+                            outputs=[height_slider],
+                        )
+                        base_thickness = gr.Number(
+                            label="Base Thickness (mm)",
+                            minimum=0,
+                            step=0.1,
+                            value=1.0,
+                        )
+                        overlay_thickness = gr.Number(
+                            label="Overlay Thickness (mm)",
+                            minimum=0,
+                            step=0.1,
+                            value=0.5,
+                        )
 
         with gr.Column():
-            out = gr.Image(label="Result")
-            mask_gallery = gr.Gallery(label="Masks")
-            base_thickness = gr.Number(
-                label="Base Thickness (mm)", minimum=0, step=0.1, value=1.0
-            )
-            overlay_thickness = gr.Number(
-                label="Overlay Thickness (mm)", minimum=0, step=0.1, value=0.5
-            )
-            width_slider = gr.Number(
-                label="Width (mm)",
-                minimum=0,
-                step=0.01,
-                value=100,
-                interactive=True,
-            )
-            height_slider = gr.Number(
-                label="Height (mm)",
-                minimum=0,
-                step=0.01,
-                value=100,
-                interactive=True,
-            )
-            use_aspect_ratio = gr.Checkbox(
-                label="Use image aspect ratio (base/overlay)",
-                value=True,
-                interactive=True,
-            )
-            height_slider.input(
-                fn=update_width_from_height,
-                inputs=[
-                    height_slider,
-                    width_slider,
-                    use_aspect_ratio,
-                    base_img,
-                    overlay_img,
-                ],
-                outputs=[width_slider],
-            )
-            width_slider.input(
-                fn=update_height_from_width,
-                inputs=[
-                    width_slider,
-                    height_slider,
-                    use_aspect_ratio,
-                    base_img,
-                    overlay_img,
-                ],
-                outputs=[height_slider],
-            )
-            masks_state = gr.State()
-            mask_colors_state = gr.State()
+            with gr.Tabs() as right_tabs:
+                with gr.Tab("Preview", id="preview"):
+                    front_out = gr.Image(label="Front Preview")
+                    back_out = gr.Image(label="Back Preview")
+                with gr.Tab("Masks", id="masks"):
+                    mask_gallery_front = gr.Gallery(label="Front Masks")
+                    mask_gallery_back = gr.Gallery(label="Back Masks")
+                with gr.Tab("Model", id="model"):
+                    animate_gif = gr.Image(
+                        label="Animation GIF",
+                        type="filepath",
+                        interactive=False,
+                    )
+                    scad_file = gr.File(label="scad/3mf archive")
+            generate_button = gr.Button("Generate Model", interactive=False)
 
-            generate_button = gr.Button("Generate scad/3mf", interactive=False)
-            scad_file = gr.File(label="SCAD/3mf output")
+    masks_state_front = gr.State()
+    mask_colors_state_front = gr.State()
+    masks_state_back = gr.State()
+    mask_colors_state_back = gr.State()
+    user_dir = gr.Text(visible=False)
 
-            masks_state.change(
-                fn=lambda masks: gr.update(interactive=bool(masks)),
-                inputs=[masks_state],
-                outputs=[generate_button],
-            )
+    qr_text_front.submit(
+        fn=generate_qr_code_from_text,
+        inputs=[qr_text_front],
+        outputs=[front_overlay_img],
+    )
+    qr_text_back.submit(
+        fn=generate_qr_code_from_text,
+        inputs=[qr_text_back],
+        outputs=[back_overlay_img],
+    )
 
-    base_img.change(
-        fn=update_slider_ranges,
-        inputs=[base_img, overlay_img, resolution_dropdown],
-        outputs=[
+    front_overlay_img.change(
+        fn=overlay_front_images,
+        inputs=[
+            base_img,
+            front_overlay_img,
             x_slider,
             y_slider,
             rot_slider,
             zoom_slider,
             indexed_slider,
-            width_slider,
-            height_slider,
+            use_common_colors_checkbox,
+            morphology_slider,
+            resolution_dropdown,
+        ],
+        outputs=[
+            front_out,
+            mask_gallery_front,
+            masks_state_front,
+            mask_colors_state_front,
+            generate_button,
         ],
     )
 
-    base_img.change(
-        fn=lambda img: (
-            gr.update(interactive=True),
-            gr.update(interactive=True),
-            gr.update(interactive=True),
-        ),
-        inputs=base_img,
-        outputs=[width_slider, height_slider, use_aspect_ratio],
-    )
-
-    overlay_img.change(
-        fn=lambda img, base, current_zoom, res: (
-            gr.update(interactive=bool(img)),
-            gr.update(interactive=bool(img)),
-            gr.update(interactive=bool(img)),
-            gr.update(
-                interactive=bool(img),
-                value=calculate_zoom_value(base, img, current_zoom, res)
-                if img
-                else current_zoom,
-            ),
-        ),
-        inputs=[overlay_img, base_img, zoom_slider, resolution_dropdown],
-        outputs=[x_slider, y_slider, rot_slider, zoom_slider],
-    )
-
-    overlay_img.change(
-        fn=update_height_from_width,
+    back_overlay_img.change(
+        fn=overlay_back_images,
         inputs=[
-            width_slider,
-            height_slider,
-            use_aspect_ratio,
             base_img,
-            overlay_img,
+            back_overlay_img,
+            x_slider_back,
+            y_slider_back,
+            rot_slider_back,
+            zoom_slider_back,
+            indexed_slider_back,
+            use_common_colors_checkbox_back,
+            morphology_slider_back,
+            resolution_dropdown,
+        ],
+        outputs=[
+            back_out,
+            mask_gallery_back,
+            masks_state_back,
+            mask_colors_state_back,
+            generate_button,
         ],
-        outputs=[height_slider],
     )
 
     for comp in [
@@ -313,41 +595,114 @@ with gr.Blocks() as demo:
         zoom_slider,
         indexed_slider,
         use_common_colors_checkbox,
-        base_img,
-        overlay_img,
         morphology_slider,
         resolution_dropdown,
     ]:
         comp.change(
-            fn=overlay_images,
+            fn=overlay_front_images,
             inputs=[
                 base_img,
-                overlay_img,
+                front_overlay_img,
                 x_slider,
                 y_slider,
                 rot_slider,
                 zoom_slider,
                 indexed_slider,
-                base_thickness,
-                overlay_thickness,
-                width_slider,
-                height_slider,
                 use_common_colors_checkbox,
                 morphology_slider,
                 resolution_dropdown,
             ],
             outputs=[
-                out,
-                mask_gallery,
-                masks_state,
-                mask_colors_state,
+                front_out,
+                mask_gallery_front,
+                masks_state_front,
+                mask_colors_state_front,
                 generate_button,
             ],
         )
 
-    resolution_dropdown.change(
+    for comp in [
+        x_slider_back,
+        y_slider_back,
+        rot_slider_back,
+        zoom_slider_back,
+        indexed_slider_back,
+        use_common_colors_checkbox_back,
+        morphology_slider_back,
+        resolution_dropdown,
+    ]:
+        comp.change(
+            fn=overlay_back_images,
+            inputs=[
+                base_img,
+                back_overlay_img,
+                x_slider_back,
+                y_slider_back,
+                rot_slider_back,
+                zoom_slider_back,
+                indexed_slider_back,
+                use_common_colors_checkbox_back,
+                morphology_slider_back,
+                resolution_dropdown,
+            ],
+            outputs=[
+                back_out,
+                mask_gallery_back,
+                masks_state_back,
+                mask_colors_state_back,
+                generate_button,
+            ],
+        )
+
+    base_img.change(
+        fn=overlay_front_images,
+        inputs=[
+            base_img,
+            front_overlay_img,
+            x_slider,
+            y_slider,
+            rot_slider,
+            zoom_slider,
+            indexed_slider,
+            use_common_colors_checkbox,
+            morphology_slider,
+            resolution_dropdown,
+        ],
+        outputs=[
+            front_out,
+            mask_gallery_front,
+            masks_state_front,
+            mask_colors_state_front,
+            generate_button,
+        ],
+    )
+
+    base_img.change(
+        fn=overlay_back_images,
+        inputs=[
+            base_img,
+            back_overlay_img,
+            x_slider_back,
+            y_slider_back,
+            rot_slider_back,
+            zoom_slider_back,
+            indexed_slider_back,
+            use_common_colors_checkbox_back,
+            morphology_slider_back,
+            resolution_dropdown,
+        ],
+        outputs=[
+            back_out,
+            mask_gallery_back,
+            masks_state_back,
+            mask_colors_state_back,
+            generate_button,
+        ],
+    )
+
+    base_img.change(
         fn=update_slider_ranges,
-        inputs=[base_img, overlay_img, resolution_dropdown],
+        inputs=[base_img, front_overlay_img, resolution_dropdown],
         outputs=[
             x_slider,
             y_slider,
@@ -359,30 +714,147 @@ with gr.Blocks() as demo:
         ],
     )
 
-    # Hidden component to hold the user directory path
-    user_dir = gr.Text(visible=False)
+    base_img.change(
+        fn=update_slider_ranges,
+        inputs=[base_img, back_overlay_img, resolution_dropdown],
+        outputs=[
+            x_slider_back,
+            y_slider_back,
+            rot_slider_back,
+            zoom_slider_back,
+            indexed_slider_back,
+            width_slider,
+            height_slider,
+        ],
+    )
+
+    front_overlay_img.change(
+        fn=update_height_from_width,
+        inputs=[
+            width_slider,
+            height_slider,
+            use_aspect_ratio,
+            base_img,
+            front_overlay_img,
+        ],
+        outputs=[height_slider],
+    )
+
+    back_overlay_img.change(
+        fn=update_height_from_width,
+        inputs=[
+            width_slider,
+            height_slider,
+            use_aspect_ratio,
+            base_img,
+            back_overlay_img,
+        ],
+        outputs=[height_slider],
+    )
+
+    front_overlay_img.change(
+        fn=lambda img, base, current_zoom, res: (
+            gr.update(interactive=bool(img)),
+            gr.update(interactive=bool(img)),
+            gr.update(interactive=bool(img)),
+            gr.update(
+                interactive=bool(img),
+                value=calculate_zoom_value(
+                    base_img=base,
+                    overlay_img=img,
+                    current_zoom=current_zoom,
+                    resolution=res,
+                )
+                if img
+                else current_zoom,
+            ),
+        ),
+        inputs=[front_overlay_img, base_img, zoom_slider, resolution_dropdown],
+        outputs=[x_slider, y_slider, rot_slider, zoom_slider],
+    )
+
+    back_overlay_img.change(
+        fn=lambda img, base, current_zoom, res: (
+            gr.update(interactive=bool(img)),
+            gr.update(interactive=bool(img)),
+            gr.update(interactive=bool(img)),
+            gr.update(
+                interactive=bool(img),
+                value=calculate_zoom_value(
+                    base_img=base,
+                    overlay_img=img,
+                    current_zoom=current_zoom,
+                    resolution=res,
+                )
+                if img
+                else current_zoom,
+            ),
+        ),
+        inputs=[
+            back_overlay_img,
+            base_img,
+            zoom_slider_back,
+            resolution_dropdown,
+        ],
+        outputs=[
+            x_slider_back,
+            y_slider_back,
+            rot_slider_back,
+            zoom_slider_back,
+        ],
+    )
+
+    resolution_dropdown.change(
+        fn=update_slider_ranges,
+        inputs=[base_img, front_overlay_img, resolution_dropdown],
+        outputs=[
+            x_slider,
+            y_slider,
+            rot_slider,
+            zoom_slider,
+            indexed_slider,
+            width_slider,
+            height_slider,
+        ],
+    )
+    resolution_dropdown.change(
+        fn=update_slider_ranges,
+        inputs=[base_img, back_overlay_img, resolution_dropdown],
+        outputs=[
+            x_slider_back,
+            y_slider_back,
+            rot_slider_back,
+            zoom_slider_back,
+            indexed_slider_back,
+            width_slider,
+            height_slider,
+        ],
+    )
 
-    # Set the user directory when the app loads
     demo.load(get_user_dir, outputs=user_dir)
+    demo.unload(delete_user_dir)
 
     generate_button.click(
-        fn=generate_3mf_file,
+        fn=switch_to_model_tab,
+        inputs=[],
+        outputs=right_tabs,
+    ).then(
+        fn=generate_3mf_with_frames,
         inputs=[
             base_img,
-            masks_state,
-            mask_colors_state,
             width_slider,
             height_slider,
             base_thickness,
             overlay_thickness,
             resolution_dropdown,
+            masks_state_front,
+            mask_colors_state_front,
+            masks_state_back,
+            mask_colors_state_back,
             user_dir,
         ],
-        outputs=[scad_file],
+        outputs=[scad_file, animate_gif],
     )
 
-    # Delete the user directory when the session ends
-    demo.unload(delete_user_dir)
-
 if __name__ == "__main__":
     demo.launch(share=False, server_name="0.0.0.0")

src/input.scad.j2

@@ -8,9 +8,9 @@ module base() {
 }
 {% endif %}
 
-module masks() {
+module front_masks() {
     scale([{{ scale_x }}, {{ scale_y }}, {{ overlay_scale_z }}]) {
-{% for mask_path, mask_color in mask_paths_and_colors %}
+{% for mask_path, mask_color in front_mask_paths_and_colors %}
         color({{ mask_color }}) linear_extrude(height = 100) projection(cut = true) {
             surface(file="{{ mask_path }}", center=false);
         }
@@ -18,11 +18,25 @@ module masks() {
     }
 }
 
+module back_masks() {
+    translate([0, 0, {{ (scale_z - overlay_scale_z) * 100 }}]) {
+        scale([{{ scale_x }}, {{ scale_y }}, {{ overlay_scale_z }}]) {
+{% for mask_path, mask_color in back_mask_paths_and_colors %}
+        color({{ mask_color }}) linear_extrude(height = 100) projection(cut = true) {
+            surface(file="{{ mask_path }}", center=false);
+        }
+{% endfor %}
+        }
+    }
+}
+
 {% if include_base %}
 difference() {
     base();
-    masks();
+    front_masks();
+    back_masks();
 }
 {% endif %}
 
-masks();
+front_masks();
+back_masks();

src/png23mf.py

@@ -1,6 +1,7 @@
 #!/usr/bin/env python3
 
 import argparse
+import logging
 import os
 import random
 import shutil
@@ -12,32 +13,131 @@ from pathlib import Path
 
 import jinja2
 import numpy as np
+import qrcode
 from PIL import Image
 from scipy import ndimage
 
+logger = logging.getLogger(__name__)
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(levelname)s - %(message)s",
+)
+
+
+def generate_random_color(*, excluded_colors=None):
+    """Generate a random RGB color not in excluded_colors."""
+    logger.debug(f"Entering generate_random_color with arguments: {locals()}")
+    if excluded_colors is None:
+        excluded_colors = set()
+        logger.debug("excluded_colors was None, set to empty set")
+    max_attempts = 1000
+    for attempt in range(1, max_attempts + 1):
+        r = random.randint(0, 255)
+        g = random.randint(0, 255)
+        b = random.randint(0, 255)
+        logger.debug(f"Attempt {attempt}: generated color ({r}, {g}, {b})")
+        if (r, g, b) not in excluded_colors:
+            result = (r, g, b)
+            break
+    else:
+        result = (0, 0, 0)
+
+    logger.debug(f"Exiting generate_random_color with value {result}")
+
+    return result
+
+
+def flip_image_horizontally(*, image):
+    """Flip an image horizontally."""
+    logger.debug(
+        f"Entering flip_image_horizontally with image size: {image.size}"
+    )
+    result = image.transpose(method=Image.Transpose.FLIP_LEFT_RIGHT)
+    logger.debug("Exiting flip_image_horizontally")
+
+    return result
+
+
+def generate_qrcode(
+    *,
+    text: str,
+    fill_color: str = "black",
+    back_color: str = "transparent",
+) -> Image.Image:
+    """Generate a QR code image."""
+    logger.debug(f"Entering generate_qrcode with arguments: {locals()}")
+    if fill_color == "random":
+        r, g, b = generate_random_color()
+        fill_color = f"#{r:02x}{g:02x}{b:02x}"
+    qr = qrcode.QRCode()
+    qr.add_data(text)
+    qr.make(fit=True)
+    result = qr.make_image(
+        fill_color=fill_color,
+        back_color=back_color,
+    ).get_image()
+    logger.debug(f"Exiting generate_qrcode with result: {result!r}")
+
+    return result
+
+
+def load_image_or_qr(*, path=None, qr_text=None):
+    """Return an RGBA image from a file path or a QR‑text."""
+    logger.debug(f"Entering load_image_or_qr with arguments: {locals()}")
+    if path is not None:
+        result = Image.open(fp=path).convert(mode="RGBA")
+    elif qr_text is not None:
+        result = generate_qrcode(text=qr_text)
+    else:
+        result = None
+    logger.debug(f"Exiting load_image_or_qr with result: {result!r}")
+
+    return result
+
+
+def get_front_image(*, path=None, qr_text=None):
+    """Return a front image from a path, QR text, or user input."""
+    logger.debug(f"Entering get_front_image with arguments: {locals()}")
+    img = load_image_or_qr(path=path, qr_text=qr_text)
+    if img is None:
+        user_input = input("Enter front image path or QR text: ")
+        logger.debug(f"User input for front image: {user_input!r}")
+        img = load_image_or_qr(path=user_input) or generate_qrcode(
+            text=user_input
+        )
+    result = img
+    logger.debug(f"Exiting get_front_image with result: {result!r}")
+
+    return result
+
 
 def generate_scad_file(
-    base_img,
-    width_mm,
-    height_mm,
-    base_thickness_mm,
-    overlay_thickness_mm,
-    resolution,
-    masks,
-    mask_colors,
+    *,
+    base_img=None,
+    width_mm: float,
+    height_mm: float,
+    base_thickness_mm: float,
+    overlay_thickness_mm: float,
+    resolution: int,
+    front_masks,
+    front_mask_colors,
+    back_masks=None,
+    back_mask_colors=None,
 ):
+    """Generate an OpenSCAD file from images and parameters."""
+    logger.debug(f"Entering generate_scad_file with arguments: {locals()}")
     include_base = base_img is not None
     tmp_dir = tempfile.mkdtemp(prefix="scad_")
-    # Base image handling
     if include_base:
-        base = base_img.convert("RGBA")
+        base = base_img.convert(mode="RGBA")
         w_base, h_base = base.size
         if max(w_base, h_base) > resolution:
             scale_factor = resolution / max(w_base, h_base)
             new_w_base = int(w_base * scale_factor)
             new_h_base = int(h_base * scale_factor)
             base = base.resize(
-                (new_w_base, new_h_base), Image.Resampling.BICUBIC
+                size=(new_w_base, new_h_base),
+                resample=Image.Resampling.BICUBIC,
             )
             w_base, h_base = base.size
         base_path = Path(tmp_dir) / "base.png"
@@ -46,13 +146,12 @@ def generate_scad_file(
         scale_y = height_mm / h_base if h_base != 0 else 1.0
         scale_z = base_thickness_mm / 100.0 if base_thickness_mm != 0 else 1.0
         base_rel_path = base_path.name
-        base_color = [0.0, 0.0, 0.0]  # placeholder, will be set below
+        base_color = [0.0, 0.0, 0.0]
     else:
-        # No base image: use overlay size for scaling
-        if masks:
-            w_overlay, h_overlay = masks[0].size
-            scale_x = width_mm / w_overlay if w_overlay != 0 else 1.0
-            scale_y = height_mm / h_overlay if h_overlay != 0 else 1.0
+        if front_masks:
+            w_front, h_front = front_masks[0].size
+            scale_x = width_mm / w_front if w_front != 0 else 1.0
+            scale_y = height_mm / h_front if h_front != 0 else 1.0
         else:
             scale_x = 1.0
             scale_y = 1.0
@@ -62,37 +161,44 @@ def generate_scad_file(
     overlay_scale_z = (
         overlay_thickness_mm / 100.0 if overlay_thickness_mm != 0 else 1.0
     )
-    # Save masks
-    mask_paths = []
-    for idx, mask_img in enumerate(masks):
-        mask_path = Path(tmp_dir) / f"mask_{idx}.png"
-        mask_img = mask_img.transpose(Image.Transpose.FLIP_LEFT_RIGHT)
+    mask_paths_front = []
+    for idx, mask_img in enumerate(front_masks):
+        mask_path = Path(tmp_dir) / f"mask_front_{idx}.png"
         mask_path.parent.mkdir(parents=True, exist_ok=True)
         mask_img.save(mask_path)
-        mask_paths.append(mask_path)
-    # Load template
+        mask_paths_front.append(mask_path)
+    mask_paths_back = []
+    if back_masks:
+        for idx, mask_img in enumerate(back_masks):
+            mask_path = Path(tmp_dir) / f"mask_back_{idx}.png"
+            mask_path.parent.mkdir(parents=True, exist_ok=True)
+            mask_img.save(mask_path)
+            mask_paths_back.append(mask_path)
     template_path = os.path.join(os.path.dirname(__file__), "input.scad.j2")
     with open(template_path, "r") as f:
         template_text = f.read()
     template = jinja2.Template(template_text)
-    mask_paths_and_colors = [
+    front_mask_paths_and_colors = [
         (mask_path.name, mask_color)
-        for mask_path, mask_color in zip(mask_paths, mask_colors)
+        for mask_path, mask_color in zip(mask_paths_front, front_mask_colors)
     ]
+    back_mask_paths_and_colors = []
+    if back_masks and back_mask_colors:
+        back_mask_paths_and_colors = [
+            (mask_path.name, mask_color)
+            for mask_path, mask_color in zip(mask_paths_back, back_mask_colors)
+        ]
     if include_base:
         mask_color_ints = set(
             (int(r * 255), int(g * 255), int(b * 255))
-            for r, g, b in mask_colors
+            for r, g, b in front_mask_colors
         )
-        max_attempts = 1000
-        for _ in range(max_attempts):
-            r = random.randint(0, 255)
-            g = random.randint(0, 255)
-            b = random.randint(0, 255)
-            if (r, g, b) not in mask_color_ints:
-                break
-        else:
-            r, g, b = 0, 0, 0
+        if back_mask_colors:
+            mask_color_ints.update(
+                (int(r * 255), int(g * 255), int(b * 255))
+                for r, g, b in back_mask_colors
+            )
+        r, g, b = generate_random_color(excluded_colors=mask_color_ints)
         base_color = [r / 255.0, g / 255.0, b / 255.0]
     rendered_scad = template.render(
         scale_x=scale_x,
@@ -100,23 +206,29 @@ def generate_scad_file(
         scale_z=scale_z,
         base_rel_path=base_rel_path,
         overlay_scale_z=overlay_scale_z,
-        mask_paths_and_colors=mask_paths_and_colors,
+        front_mask_paths_and_colors=front_mask_paths_and_colors,
+        back_mask_paths_and_colors=back_mask_paths_and_colors,
         base_color=base_color,
         include_base=include_base,
     )
     scad_path = Path(tmp_dir) / "model.scad"
     with open(scad_path, "w") as f:
         f.write(rendered_scad)
-    return str(scad_path)
+    result = str(scad_path)
+    logger.debug(f"Exiting generate_scad_file with result: {result!r}")
 
+    return result
 
-def extract_masks(overlay_image, morph_size=1):
-    overlay_rgba = overlay_image.convert("RGBA")
-    overlay_np = np.array(overlay_rgba)
+
+def extract_masks(*, overlay_image, morph_size=1):
+    """Extract masks and corresponding colors from an overlay image."""
+    logger.debug(f"Entering extract_masks with arguments: {locals()}")
+    overlay_rgba = overlay_image.convert(mode="RGBA")
+    overlay_np = np.array(object=overlay_rgba)
     alpha_mask = overlay_np[..., 3] != 0
     flat = overlay_np.reshape(-1, 4)
-    unique_colors = np.unique(flat, axis=0)
-    unique_colors = unique_colors[unique_colors[:, 3] != 0]
+    unique_colors = np.unique(ar=flat, axis=0)
+    unique_colors = unique_colors[unique_colors[..., 3] != 0]
     masks = []
     mask_colors = []
     selem = np.ones((int(morph_size), int(morph_size)), dtype=bool)
@@ -124,52 +236,51 @@ def extract_masks(overlay_image, morph_size=1):
         mask_array = (
             np.all(overlay_np[..., :3] == color[:3], axis=-1) & alpha_mask
         )
-        opened = ndimage.binary_opening(mask_array, structure=selem)
-        closed = ndimage.binary_closing(opened, structure=selem)
-        mask_image = Image.fromarray((closed.astype(np.uint8) * 255), mode="L")
+        opened = ndimage.binary_opening(input=mask_array, structure=selem)
+        closed = ndimage.binary_closing(input=opened, structure=selem)
+        mask_image = Image.fromarray(
+            obj=(closed.astype(np.uint8) * 255),
+            mode="L",
+        )
         masks.append(mask_image)
         r = int(color[0]) / 255.0
         g = int(color[1]) / 255.0
         b = int(color[2]) / 255.0
         mask_colors.append([r, g, b])
-    return masks, mask_colors
-
-
-def calculate_zoom_value(base_img, overlay_img, current_zoom, resolution):
-    if base_img is None or overlay_img is None:
-        return current_zoom
-    base = base_img.convert("RGBA")
-    w_base, h_base = base.size
-    if max(w_base, h_base) > resolution:
-        scale_factor = resolution / max(w_base, h_base)
-        w_base = int(w_base * scale_factor)
-        h_base = int(h_base * scale_factor)
-    base_longer = max(w_base, h_base)
-    w_overlay, h_overlay = overlay_img.size
-    overlay_longer = max(w_overlay, h_overlay)
-    if overlay_longer > base_longer:
-        zoom = round(base_longer / overlay_longer, 2)
-        zoom = max(0.01, min(10.0, zoom))
-        return zoom
-    else:
-        return current_zoom
+    result = (masks, mask_colors)
+    logger.debug(f"Exiting extract_masks with result: {result!r}")
+
+    return result
 
 
-def get_most_common_colors(overlay_img, num_colors):
-    rgba = overlay_img.convert("RGBA")
-    arr = np.array(rgba)
+def get_most_common_colors(*, overlay_img, num_colors):
+    """Return the most common colors in the overlay image."""
+    logger.debug(f"Entering get_most_common_colors with arguments: {locals()}")
+    rgba = overlay_img.convert(mode="RGBA")
+    arr = np.array(object=rgba)
     alpha_mask = arr[..., 3] > 0
     rgb_pixels = arr[alpha_mask][:, :3]
     if rgb_pixels.size == 0:
-        return [(0, 0, 0)] * num_colors
-    unique_colors, counts = np.unique(rgb_pixels, axis=0, return_counts=True)
+        result = [(0, 0, 0)] * num_colors
+        logger.debug(f"Exiting get_most_common_colors with result: {result!r}")
+        return result
+    unique_colors, counts = np.unique(
+        ar=rgb_pixels,
+        axis=0,
+        return_counts=True,
+    )
     sorted_indices = np.argsort(-counts)
     sorted_colors = unique_colors[sorted_indices]
     top_colors = sorted_colors[:num_colors]
-    return [tuple(color) for color in top_colors]
+    result = [tuple(color) for color in top_colors]
+    logger.debug(f"Exiting get_most_common_colors with result: {result!r}")
+
+    return result
 
 
-def create_palette_image(colors):
+def create_palette_image(*, colors):
+    """Create a palette image from a list of RGB colors."""
+    logger.debug(f"Entering create_palette_image with arguments: {locals()}")
     palette = [0] * 768
     for i, color in enumerate(colors):
         if i >= 256:
@@ -182,148 +293,265 @@ def create_palette_image(colors):
         palette[i * 3] = last_color[0]
         palette[i * 3 + 1] = last_color[1]
         palette[i * 3 + 2] = last_color[2]
-    palette_img = Image.new("P", (1, 1))
+    palette_img = Image.new(mode="P", size=(1, 1))
     palette_img.putpalette(palette)
-    return palette_img
+    result = palette_img
+    logger.debug(f"Exiting create_palette_image with result: {result!r}")
+
+    return result
 
 
 def overlay_images_core(
-    base_img,
+    *,
+    base_img=None,
     overlay_img,
-    x,
-    y,
-    rot,
-    zoom,
-    indexed_colors,
-    base_thickness,
-    overlay_thickness,
-    width,
-    height,
-    use_common_colors,
-    morph_size,
-    resolution,
+    x: int,
+    y: int,
+    rot: int,
+    zoom: float,
+    indexed_colors: int,
+    use_common_colors: bool,
+    morph_size: int,
+    resolution: int,
 ):
+    """Overlay an image onto a base image and extract masks."""
+    logger.debug(f"Entering overlay_images_core: with arguments: {locals()}")
     if overlay_img is None:
-        return None, None, None
-    width = round(width, 2)
-    height = round(height, 2)
+        result = (None, None, None)
+        logger.debug(
+            "Exiting overlay_images_core with result: (None, None, None)"
+        )
+        return result
+    overlay = overlay_img.convert(mode="RGBA")
+    logger.debug(f"Overlay image converted to RGBA: size={overlay.size}")
+    w, h = overlay.size
+    logger.debug(f"Overlay size: {w}x{h}")
+
+    if base_img is None and (w > resolution or h > resolution):
+        scale_factor = resolution / max(w, h)
+        new_w = int(w * scale_factor)
+        new_h = int(h * scale_factor)
+        w, h = new_w, new_h
+        logger.debug(
+            f"Scaled overlay to resolution {resolution}: new size={w}x{h}"
+        )
+
     if base_img is None:
-        base = overlay_img.convert("RGBA")
+        base = Image.new(mode="RGBA", size=(w, h), color=(0, 0, 0, 0))
+        logger.debug(
+            f"No base image - created base image with size={base.size}"
+        )
         x, y = 0, 0
     else:
-        base = base_img.convert("RGBA")
+        base = base_img.convert(mode="RGBA")
         w_base, h_base = base.size
         max_dim = resolution
         if max(w_base, h_base) > max_dim:
             scale_factor = max_dim / max(w_base, h_base)
-            new_w_base = int(w_base * scale_factor)
-            new_h_base = int(h_base * scale_factor)
+            new_w_base = round(w_base * scale_factor)
+            new_h_base = round(h_base * scale_factor)
             base = base.resize(
-                (new_w_base, new_h_base), Image.Resampling.BICUBIC
+                size=(new_w_base, new_h_base),
+                resample=Image.Resampling.BICUBIC,
             )
-    overlay = overlay_img.convert("RGBA")
-    w, h = overlay.size
+            logger.debug(
+                f"Resized base image to {base.size} "
+                f"to fit resolution {resolution}"
+            )
+        else:
+            logger.debug(
+                f"Base image size {base.size} within resolution limit"
+            )
+
     overlay = overlay.resize(
-        (int(w * zoom), int(h * zoom)), Image.Resampling.NEAREST
+        size=(int(w * zoom), int(h * zoom)),
+        resample=Image.Resampling.NEAREST,
     )
-    overlay = overlay.rotate(rot, expand=True)
+    logger.debug(f"Scaled overlay with zoom {zoom}: new size={overlay.size}")
+
+    if rot != 0:
+        overlay = overlay.rotate(angle=rot, expand=True)
+        logger.debug(
+            f"Rotated overlay by {rot} degrees: new size={overlay.size}"
+        )
+
     alpha = overlay.split()[3]
-    rgb = overlay.convert("RGB")
+    rgb = overlay.convert(mode="RGB")
+
     if use_common_colors:
-        common_colors = get_most_common_colors(overlay_img, indexed_colors)
-        palette_img = create_palette_image(common_colors)
-        rgb_quant = rgb.quantize(palette=palette_img, dither=0).convert("RGB")
+        common_colors = get_most_common_colors(
+            overlay_img=overlay_img,
+            num_colors=indexed_colors,
+        )
+        logger.debug(f"Using common colors: {common_colors}")
+        palette_img = create_palette_image(colors=common_colors)
+        rgb_quant = rgb.quantize(
+            palette=palette_img,
+            dither=0,
+        ).convert(mode="RGB")
+        logger.debug(
+            f"Quantized overlay using common colors to {indexed_colors} colors"
+        )
     else:
-        rgb_quant = rgb.quantize(colors=indexed_colors).convert("RGB")
+        rgb_quant = rgb.quantize(colors=indexed_colors).convert(mode="RGB")
+        logger.debug(f"Quantized overlay to {indexed_colors} colors")
+
     alpha = overlay.split()[3].point(lambda p: 255 if p > 0 else 0)
-    overlay = Image.merge("RGBA", (*rgb_quant.split(), alpha))
-    if base_img is not None:
-        base.paste(overlay, (int(x), int(y)), overlay)
-    overlay_on_transparent = Image.new("RGBA", base.size, (0, 0, 0, 0))
-    overlay_on_transparent.paste(overlay, (int(x), int(y)), overlay)
-    masks, mask_colors = extract_masks(overlay_on_transparent, morph_size)
-    return (
-        base.convert("RGB"),
-        masks,
-        mask_colors,
+    overlay = Image.merge(
+        mode="RGBA",
+        bands=(*rgb_quant.split(), alpha),
     )
+    logger.debug("Overlay image merged with quantized RGB and alpha channel")
 
+    base.paste(im=overlay, box=(int(x), int(y)), mask=overlay)
+    logger.debug(f"Pasted overlay onto base at position ({x}, {y})")
 
-def update_width_from_height(
-    height,
-    width,
-    use_aspect_ratio,
-    base_img,
-    overlay_img,
-):
-    if use_aspect_ratio:
-        if base_img is not None:
-            w_base, h_base = base_img.size
-        elif overlay_img is not None:
-            w_base, h_base = overlay_img.size
-        else:
-            return width
-        new_width = round(height * w_base / h_base, 2)
-        if abs(new_width - width) > 1e-6:
-            return new_width
-    return width
+    overlay_on_transparent = Image.new(
+        mode="RGBA",
+        size=base.size,
+        color=(0, 0, 0, 0),
+    )
+    overlay_on_transparent.paste(
+        im=overlay,
+        box=(int(x), int(y)),
+        mask=overlay,
+    )
+    logger.debug(
+        "Created overlay_on_transparent image with "
+        f"size={overlay_on_transparent.size}"
+    )
 
+    masks, mask_colors = extract_masks(
+        overlay_image=overlay_on_transparent,
+        morph_size=morph_size,
+    )
+    logger.debug(f"Extracted {len(masks)} masks from overlay")
 
-def update_height_from_width(
-    width,
-    height,
-    use_aspect_ratio,
-    base_img,
-    overlay_img,
-):
-    if use_aspect_ratio:
-        if base_img is not None:
-            w_base, h_base = base_img.size
-        elif overlay_img is not None:
-            w_base, h_base = overlay_img.size
-        else:
-            return height
-        new_height = round(width * h_base / w_base, 2)
-        if abs(new_height - height) > 1e-6:
-            return new_height
-    return height
+    response = (base.convert(mode="RGB"), masks, mask_colors)
+    logger.debug(f"Exiting overlay_images_core with result: {response!r}")
+
+    return response
+
+
+def render_animation_frames(*, model_3mf, animate_frames, temp_dir):
+    """Render animation frames for the 3MF model."""
+    logger.debug(
+        f"Entering render_animation_frames with arguments: {locals()}"
+    )
+    template_path = os.path.join(os.path.dirname(__file__), "animate.scad.j2")
+    with open(template_path, "r") as f:
+        template_text = f.read()
+    template = jinja2.Template(template_text)
+    relative_model_path = os.path.relpath(str(model_3mf), start=str(temp_dir))
+    rendered_scad = template.render(model_path=relative_model_path)
+    animate_scad_path = temp_dir / "animate.scad"
+    animate_scad_path.write_text(rendered_scad)
+
+    output_prefix = temp_dir / "model_"
+    subprocess.run(
+        args=[
+            "openscad",
+            "--camera",
+            "0,0,10,0,0,0",
+            "--viewall",
+            "--animate",
+            str(animate_frames),
+            "--projection",
+            "perspective",
+            "-o",
+            f"{output_prefix}.png",
+            str(animate_scad_path),
+        ],
+        check=True,
+    )
+    logger.debug("Exiting render_animation_frames with result: None")
+    result = None
+
+    return result
+
+
+def convert_frames_to_gif(*, temp_dir):
+    """Convert rendered frames to a GIF animation."""
+    logger.debug(f"Entering convert_frames_to_gif with arguments: {locals()}")
+    frame_files = sorted(temp_dir.glob("model_*.png"))
+    if not frame_files:
+        logger.debug("Exiting convert_frames_to_gif with result: None")
+        result = None
+        return result
+    frames = [Image.open(fp=fp) for fp in frame_files]
+    gif_path = temp_dir / "animation.gif"
+    frames[0].save(
+        fp=gif_path,
+        save_all=True,
+        append_images=frames[1:],
+        duration=100,
+        loop=0,
+    )
+    for f in frames[1:]:
+        f.close()
+    frames[0].close()
+    logger.debug(f"Exiting convert_frames_to_gif with result: {gif_path!r}")
+    result = gif_path
+
+    return result
 
 
 def generate_3mf_file(
     base_img,
-    masks,
-    mask_colors,
     width,
     height,
     base_thickness,
     overlay_thickness,
     resolution,
+    front_masks,
+    front_mask_colors,
+    back_masks=None,
+    back_mask_colors=None,
     user_dir=None,
+    animate_frames=0,
 ):
-    if not masks or not mask_colors:
-        return None
+    """Generate a 3MF file and optional GIF animation."""
+    logger.debug(f"Entering generate_3mf_file with arguments: {locals()}")
+    if not front_masks or not front_mask_colors:
+        logger.debug("Exiting generate_3mf_file with result: None")
+        result = None
+        return result
+    logger.debug("Flipping front masks horizontally before generating 3MF")
+    front_masks = [flip_image_horizontally(image=mask) for mask in front_masks]
+    if base_img is not None:
+        logger.debug("Flipping base image horizontally before generating 3MF")
+        base_img = flip_image_horizontally(image=base_img)
     scad_path = generate_scad_file(
-        base_img,
-        width,
-        height,
-        base_thickness,
-        overlay_thickness,
-        resolution,
-        masks,
-        mask_colors,
+        base_img=base_img,
+        width_mm=width,
+        height_mm=height,
+        base_thickness_mm=base_thickness,
+        overlay_thickness_mm=overlay_thickness,
+        resolution=resolution,
+        front_masks=front_masks,
+        front_mask_colors=front_mask_colors,
+        back_masks=back_masks,
+        back_mask_colors=back_mask_colors,
     )
     if not scad_path:
-        return None
+        logger.debug("Exiting generate_3mf_file with result: None")
+        result = None
+        return result
     scad_path_obj = Path(scad_path)
     openscad_model_3mf = scad_path_obj.with_name("openscad_model.3mf")
     subprocess.run(
-        ["openscad", "-o", str(openscad_model_3mf), str(scad_path_obj)],
+        args=[
+            "openscad",
+            "-o",
+            str(openscad_model_3mf),
+            str(scad_path_obj),
+        ],
         check=True,
     )
     converted_model_3mf = openscad_model_3mf.with_name("converted_model.3mf")
     script_path = Path(__file__).parent / "3mf2mmuv3.py"
     subprocess.run(
-        [
+        args=[
             "python3",
             str(script_path),
             str(openscad_model_3mf),
@@ -333,7 +561,9 @@ def generate_3mf_file(
         check=True,
     )
     temp_dir = scad_path_obj.parent
-    mask_paths = sorted(Path(temp_dir).glob("mask_*.png"))
+    mask_paths_front = sorted(Path(temp_dir).glob("mask_front_*.png"))
+    mask_paths_back = sorted(Path(temp_dir).glob("mask_back_*.png"))
+    mask_paths = mask_paths_front + mask_paths_back
     random_string = "".join(
         random.choices(string.ascii_letters + string.digits, k=6)
     )
@@ -343,8 +573,30 @@ def generate_3mf_file(
         zip_path = zip_dir / f"model_{random_string}.zip"
     else:
         zip_path = Path(tempfile.gettempdir()) / f"model_{random_string}.zip"
+    if animate_frames and animate_frames > 0:
+        render_animation_frames(
+            model_3mf=openscad_model_3mf,
+            animate_frames=animate_frames,
+            temp_dir=temp_dir,
+        )
+    gif_path = None
+    gif_path_to_return = None
+    if animate_frames and animate_frames > 0:
+        gif_path = convert_frames_to_gif(temp_dir=temp_dir)
+        if gif_path:
+            if user_dir:
+                dest_dir = Path(user_dir)
+                dest_dir.mkdir(parents=True, exist_ok=True)
+                gif_dest_path = dest_dir / gif_path.name
+                shutil.copy(src=gif_path, dst=gif_dest_path)
+                gif_path_to_return = str(gif_dest_path)
+            else:
+                gif_path_to_return = str(gif_path)
     with zipfile.ZipFile(
-        zip_path, "w", zipfile.ZIP_DEFLATED, compresslevel=9
+        zip_path,
+        mode="w",
+        compression=zipfile.ZIP_DEFLATED,
+        compresslevel=9,
     ) as zf:
         zf.write(scad_path_obj, arcname=scad_path_obj.name)
         zf.write(openscad_model_3mf, arcname=openscad_model_3mf.name)
@@ -354,24 +606,63 @@ def generate_3mf_file(
         if base_img is not None:
             base_img_path = Path(temp_dir) / "base.png"
             zf.write(base_img_path, arcname=base_img_path.name)
+        if animate_frames and animate_frames > 0:
+            animate_scad_path = temp_dir / "animate.scad"
+            zf.write(animate_scad_path, arcname=animate_scad_path.name)
+            frame_files = sorted(temp_dir.glob("model_*.png"))
+            for frame_file in frame_files:
+                zf.write(frame_file, arcname=frame_file.name)
+        if gif_path:
+            zf.write(gif_path, arcname=gif_path.name)
     shutil.rmtree(temp_dir)
-    return str(zip_path)
+    logger.debug(f"Removed {temp_dir}")
+    result = (str(zip_path), gif_path_to_return)
+    logger.debug(f"Exiting generate_3mf_file with result: {result!r}")
+
+    return result
 
 
 def main():
+    """Main entry point for generating 3MF files from images."""
+    logger.debug(f"Entering main with arguments: {locals()}")
     parser = argparse.ArgumentParser(
         description="Generate 3MF from base and overlay images."
     )
-    parser.add_argument("base_image", help="Path to base image (PNG)")
-    parser.add_argument("overlay_image", help="Path to overlay image (PNG)")
     parser.add_argument(
-        "-o", "--output", default=None, help="Output zip file path (optional)"
+        "--base-image",
+        dest="base_image",
+        help="Path to base image (PNG, optional)",
+        default=None,
     )
     parser.add_argument(
-        "--width", type=float, default=100.0, help="Width in mm"
+        "--front-image",
+        dest="front_image",
+        help="Path to front image (PNG, optional)",
+        required=False,
     )
     parser.add_argument(
-        "--height", type=float, default=100.0, help="Height in mm"
+        "--back-image",
+        dest="back_image",
+        help="Path to back image (PNG, optional)",
+        default=None,
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        default=None,
+        help="Output zip file path (optional)",
+    )
+    parser.add_argument(
+        "--width",
+        type=float,
+        default=100.0,
+        help="Width in mm",
+    )
+    parser.add_argument(
+        "--height",
+        type=float,
+        default=100.0,
+        help="Height in mm",
     )
     parser.add_argument(
         "--base-thickness",
@@ -398,11 +689,13 @@ def main():
         default=1,
         help="Morphology size for mask extraction",
     )
-    # New arguments that mirror the Gradio UI
     parser.add_argument("--x", type=int, default=0, help="X offset (px)")
     parser.add_argument("--y", type=int, default=0, help="Y offset (px)")
     parser.add_argument(
-        "--rot", type=int, default=0, help="Rotation (degrees)"
+        "--rot",
+        type=int,
+        default=0,
+        help="Rotation (degrees)",
     )
     parser.add_argument("--zoom", type=float, default=1.0, help="Zoom factor")
     parser.add_argument(
@@ -417,54 +710,109 @@ def main():
         default=True,
         help="Use most common colors for quantization",
     )
+    parser.add_argument(
+        "--animate",
+        type=int,
+        default=0,
+        help="Number of frames to render for animation",
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        default=False,
+        help="Enable debug output",
+    )
+    parser.add_argument(
+        "--front-qr",
+        dest="front_qr",
+        help="Text to generate a QR code for front image",
+        default=None,
+    )
+    parser.add_argument(
+        "--back-qr",
+        dest="back_qr",
+        help="Text to generate a QR code for back image",
+        default=None,
+    )
     args = parser.parse_args()
 
-    # Load images
-    base_img = Image.open(args.base_image).convert("RGBA")
-    overlay_img = Image.open(args.overlay_image).convert("RGBA")
-
-    # Generate masks and mask colors using overlay images core logic
-    _, masks, mask_colors = overlay_images_core(
-        base_img,
-        overlay_img,
-        args.x,
-        args.y,
-        args.rot,
-        args.zoom,
-        args.indexed_colors,
-        args.base_thickness,
-        args.overlay_thickness,
-        args.width,
-        args.height,
-        args.use_common_colors,
-        args.morph_size,
-        args.resolution,
-    )
-
-    if not masks or not mask_colors:
-        print("Failed to generate masks from overlay image.")
+    if args.debug:
+        logger.setLevel(logging.DEBUG)
+        logger.debug("Debug logging enabled")
+
+    base_img = load_image_or_qr(path=args.base_image)
+    front_img = get_front_image(path=args.front_image, qr_text=args.front_qr)
+    back_img = load_image_or_qr(path=args.back_image, qr_text=args.back_qr)
+
+    logger.info(f"Parsed arguments: {args}")
+
+    _, front_masks, front_mask_colors = overlay_images_core(
+        base_img=base_img,
+        overlay_img=front_img,
+        x=args.x,
+        y=args.y,
+        rot=args.rot,
+        zoom=args.zoom,
+        indexed_colors=args.indexed_colors,
+        use_common_colors=args.use_common_colors,
+        morph_size=args.morph_size,
+        resolution=args.resolution,
+    )
+    if front_masks is None:
+        logger.error("Failed to generate masks from front image.")
+        logger.debug("Exiting main with result: None")
+
+        return
+
+    if back_img:
+        _, back_masks, back_mask_colors = overlay_images_core(
+            base_img=base_img,
+            overlay_img=back_img,
+            x=args.x,
+            y=args.y,
+            rot=args.rot,
+            zoom=args.zoom,
+            indexed_colors=args.indexed_colors,
+            use_common_colors=args.use_common_colors,
+            morph_size=args.morph_size,
+            resolution=args.resolution,
+        )
+    else:
+        back_masks = None
+        back_mask_colors = None
+
+    if not front_masks or not front_mask_colors:
+        logger.error("Failed to generate masks from front image.")
+        logger.debug("Exiting main with result: None")
+
         return
 
     zip_path = generate_3mf_file(
-        base_img,
-        masks,
-        mask_colors,
-        args.width,
-        args.height,
-        args.base_thickness,
-        args.overlay_thickness,
-        args.resolution,
+        base_img=base_img,
+        front_masks=front_masks,
+        front_mask_colors=front_mask_colors,
+        back_masks=back_masks,
+        back_mask_colors=back_mask_colors,
+        width=args.width,
+        height=args.height,
+        base_thickness=args.base_thickness,
+        overlay_thickness=args.overlay_thickness,
+        resolution=args.resolution,
+        animate_frames=args.animate,
     )
 
     if zip_path is None:
-        print("Failed to generate 3MF zip.")
+        logger.error("Failed to generate 3MF zip.")
+        logger.debug("Exiting main with result: None")
+
         return
 
     if args.output:
-        shutil.move(zip_path, args.output)
-        print(f"Generated zip file: {args.output}")
+        shutil.move(src=zip_path[0], dst=args.output)
+        logger.info(f"Generated zip file: {args.output}. Parsed args: {args}")
     else:
-        print(f"Generated zip file: {zip_path}")
+        logger.info(f"Generated zip file: {zip_path}. Parsed args: {args}")
+    logger.debug("Exiting main with result: None")
 
 
 if __name__ == "__main__":