Preface

December 9, 2025 · View on GitHub

Preface

Scratch Hologram is a technique that creates three-dimensional visual effects by engraving specific curved lines onto the surface of reflective materials. The principle is based on the specular reflection of light. As the viewer moves, scratches at different positions reflect light at changing angles, producing motion parallax and thereby forming dynamic 3D images. This technology is simple to produce, low-cost, and widely used in areas such as anti-counterfeiting labels, artistic creation, and educational demonstrations. Compared to traditional holographic techniques, it does not require complex optical equipment; three-dimensional visual effects can be achieved simply by engraving regular arcs onto materials like acrylic or metal plates, either by hand or machine.

EZHolo Introduction

EZHolodotNet (EZHolo) is a .NET-based interactive tool that automatically generates scratch hologram trajectories from 2D images + depth maps, providing 3D preview, post-processing, and multiple export formats. It supports the open-source depth estimation model Depth Anything v2, automatic sampling, manual refinement, occlusion calculation, and manual engraving drawing generation, catering to creators and engineers.

0. Rationale & Applicability

0.1 Why EZHolo?

The traditional scratch hologram workflow typically requires 3D modeling, scripting, and using plugins in 3D software like Rhino/Blender to calculate trajectories. This includes:

Determining the curvature and direction of each scratch based on depth;
Avoiding scratches that are too dense or completely "scratch through the board" in local areas;
Handling occlusion relationships to prevent structures hidden behind from appearing in incorrect viewing angles.

EZHolo aims to: Package this entire set of geometric and engineering details, allowing you to easily create scratch trajectories based on 2D images.

0.2 Prerequisites / Non-Applicable Situations

Depth Information is Mandatory
- It is strongly recommended to download the Depth Anything v2 series models to the software directory. EZHolo will automatically estimate the depth map after opening the original image.
- If you do not download the model, you can also use external tools to generate a depth map and then import it into EZHolo.
⚠️ If you have neither the model nor a depth map, this software cannot produce satisfactory results.
Applicable For
- Having good 2D image resources (photos, drawings, 3D renderings, etc.);
- Wanting to create your own scratch hologram cards, metal plates, acrylic plates;
- Needing to generate paths for CNC writing machines, engravers, lithography/engraving processes;
Not Applicable For
- Creating scratch holograms from 3D model files?
  - EZHolo currently does not support direct import of 3D model files (e.g., OBJ, STL) for processing. It is recommended to use dedicated scratch hologram generation tools for 3D models, such as Holocraft. Alternatively, first render 2D images and/or depth maps from 3D software, then import them into EZHolo.
- Creating rotating scratch holograms?
  - EZHolo is a tool for generating circular arc scratch hologram trajectories and does not support rotating scratch hologram trajectory generation. If you want to generate rotating scratch holograms, please refer to the EZHolo Prototype Design or Rotary "Scratch Hologram" Code Sharing (with Occlusion) - @Earshu - Bilibili

1. Installation & Environment Setup

If you encounter issues during the process, feel free to join the

1.1 Download

Go to the release page to get the latest version:
👉 Latest windows_anycpu release version

Run the EXE directly after extraction.

1.2 Configure Depth Anything v2 ONNX Model

Download the Depth Anything v2 ONNX model (e.g., depth_anything_v2_vitb.onnx).
- Click here to download the standard-size model (depth_anything_v2_vitb.onnx - 371 MB). For more models (other sizes, dynamic adaption, indoor/outdoor fine-tuning), click here
Place the model file (.onnx) and the software (EZHolodotNet.exe) in the same directory.
The software will automatically load the model on the next launch:
- After importing the original image, the software will immediately perform inference and generate the depth map;
- You no longer need to manually import the depth map a second time.

💡 Optional: You can also download multiple models of different sizes, dynamic adaption, or fine-tuned for indoor/outdoor, and place them in the same directory. You can adjust which model to load from within the software.

⚠️ Not Recommended: If you don't want to download the model, you can also use EZHolo by importing your own prepared depth map—but the software cannot work without a depth map.

2. Standard Workflow

This section is a step-by-step tutorial for the "make a board from scratch" process, for first-time EZHolo users.

Step 1: Import Original Image (Auto/Manual Depth Generation)

Import the original image in the left image area:
- Menu "Open Image";
- Or directly drag and drop the image into the original image area;
- Or copy the image and press Ctrl + V in the main interface to paste (a copy will be saved in the user's picture directory).
If the Depth Anything v2 ONNX model is already placed in the directory, the software will automatically load the model and generate the corresponding depth map immediately after importing the original image.
If there is no model, you need to manually provide a depth map (menu "Open Depth Map" or drag the depth map into the depth area).

Step 2: Keypoint Sampling – Select Points for Trajectory Generation

Core Goal: Obtain a "key sampled points map"; subsequent trajectories are generated around these points.

2.1 Basic Sampling: Contour + Luminance

Recommended order:

First, perform contour sampling based on depth to capture the overall outline
- Enable "Based on Depth" mode in Contour Sampling;
- Execute contour sampling to get the main outline based on depth gradient;
- Click "Transfer to Manual Sampling" to move this batch of points into manual sampling mode.
Turn off "Based on Depth" and use regular (color-based) contour sampling to add details
- Disable the "Based on Depth" option;
- Run contour sampling again to supplement detailed contours using color information;
- Click "Transfer to Manual Sampling" again to merge into the same manual point set.
Luminance Sampling (Optional)
- If there are highlights, light-emitting objects, or special textures in the image, you can perform luminance sampling;
- Also merge into the manual set via "Transfer to Manual Sampling".

In the "Manual Sampling" tool group, it's recommended to refine the point set as follows:

Eraser to Clean Up Background
- Set the eraser's "Shallowest/Deepest Erasable Height" to the depth range of the background;
- Brush roughly over the background area to quickly remove unnecessary background points.
Gradient Offset Small Steps Multiple Times
- Use the gradient offset tool to perform a "1% offset in gradient direction" globally;
- Repeat small offsets multiple times. This is more stable than a single large offset and helps the point distribution better conform to depth changes.
Density Reduction Tool for Deduplication
- Use the density reduction tool to control the total number of points and local density;
- Alleviate areas where trajectories are too dense and might scratch through the board.

2.3 (Optional) Save Point Map for Future Use

Export in the menu File → Point Map:
- PNG Point Map (Combined / Manual Only); or
- SVG Point Map (Combined / Manual Only, all sampling points saved as <circle />).
Next time, you can re-import the current set of sampling points via "Import Point Map", avoiding starting from scratch.

Step 3: Scratch Trajectory Generation

This stage transforms "points" into "scratches that can be made."

3.1 Standard Mode (Default)

Keep the Standard Mode selected in "Trajectory Generation Mode" (default).
Adjust the "Zero Height" parameter to make the overall "convex/concave" and arc curvature more like your desired spatial layout.
Curvature Coefficient and Stretch Coefficient are advanced parameters:
- For first-time use, it's recommended to leave them unchanged initially;
- If the printed result is unsatisfactory, adjust based on practical testing or ask in the group.

3.2 Occlusion Calculation Mode (Optional, v2.0+)

After confirming the trajectory is roughly OK in Standard Mode, switch the trajectory generation mode to Occlusion Calculation Mode;
The software will perform foreground occlusion analysis and Bézier segment clipping based on depth information. Progress will be shown in the task list in the bottom right corner;
After completion, you will get a set of trajectories that "consider occlusion." Preview and export will reflect the real front-back relationships.

3.3 Manual Engraving Mode (Optional)

If you plan to engrave purely by hand and:

Do not need such complex Bézier trajectories;
Prefer more structured, more readable line drawings;

You can try switching the mode to Manual Engraving Mode:

Trajectories are no longer cubic Bézier curves but arcs of different radii;
To simplify the structure, occlusion calculation is not included;
More suitable as a base for manual engraving drawings.

Step 4: Preview

4.1 Dynamic Preview

Open the dynamic preview window, adjust the step value, and observe the effect from different viewing angles;
This preview is for interactive viewing only and will not export image files.

4.2 3D View (Optional)

If you know the parallel view / cross-eye technique for viewing stereograms, you can click the 3D View button;
Generates a parallel stereogram, supporting auto-play and mode switching, convenient for verifying the final spatial effect.

Step 5: Export

The exported content differs depending on the trajectory generation mode you selected in Step 3.

5.1 Export in Standard / Occlusion Mode

The exported SVG file contains many trajectory segments, with each sampling point corresponding to one or more curve segments;
It can be used by:
- Writing machines / plotters;
- Laser / CNC engravers;
- Or imported into software like Blender for optical simulation or other custom workflows.

5.2 Export in Manual Engraving Mode

The export result is a folder containing:
- Multiple SVG files (layered manual engraving drawings);
- An HTML file;
Open the HTML file in a browser for simple layout and print output;
After printing, use a compass/engraving needle for purely manual scratching/engraving.

3. Feature Overview (Reference Guide)

This section is a feature index, not emphasizing the order of operation, for easy lookup of "if and where" certain functionalities exist.

3.1 Sampling & Configuration

Automatic Sampling Strategies
- Contour Sampling:
  - Supports regular contour sampling based on color;
  - Supports "Depth-based" contour sampling, placing points at positions with high depth gradient, with optional binary denoising.
- Luminance Sampling:
  - Samples according to brightness distribution, suitable for highlights, light-emitting objects, texture areas.
Manual Sampling
- Brush to add points, eraser to delete points;
- Supports erasure restriction by depth range;
- Supports import/export of point data.
Sampling Result Management
- Various sampling strategies can be "Transferred to Manual Sampling";
- Point Map Import/Export:
  - PNG Point Map (Combined / Manual Only);
  - SVG Point Map (Combined / Manual Only, points represented as <circle />).
Configuration Management
- Configuration Import/Export;
- Supports "Use last session's configuration on startup".

3.2 Post-Sampling Processing & Refinement Tools

Smudge Tool: Smoothes abnormal outer edge sampling points inward;
Gradient Offset Tool:
- Local smudging or global offset;
- Moves points slightly along the depth gradient direction or opposite direction;
Advanced Deduplication / Density Reduction Tool:
- Uniformly reduces point count, controls local density;
Enhanced Eraser Tool:
- Intelligent Edge Eraser;
- Shallowest/Deepest erasable height constraints.

3.3 Visualization & Interface

Height Indicator (on both sides of the image + bottom right corner);
Gradient Indicator (shows gradient magnitude and direction);
Trajectory Density Display:
- Heatmap form revealing overlapping dense areas;
- Shows highest overlap count in the top-left corner;
Three-View Linkage:
- Original Image / Depth Map / Sampling Result synchronized;
- Mouse middle button drag to move view, Ctrl + scroll wheel to zoom;
- Shift + scroll wheel adjusts sampling point map/depth map scale;
- Press Ctrl and move the mouse to display information at the same position across all three views;
- Three-view height adjustable by dragging;
Displays current depth value next to the cursor on hover;
Multi-language (machine-translated) Interface: Simplified Chinese, Traditional Chinese, English, Japanese, French, Russian, German, etc.

3.4 Trajectory Generation & Preview

Trajectory Generation Modes:
- Standard Mode;
- Occlusion Calculation Mode (considers foreground occlusion, performs Bézier segment clipping);
- Manual Engraving Mode (no occlusion, simplifies trajectories using arcs of different radii).
Parameters:
- Zero Height;
- Curvature Coefficient;
- Stretch Coefficient;
- And other trajectory shape-related parameters.
Preview:
- Scratch Preview;
- 3D Preview (Parallel Eye / Cross Eye, supports auto-play).

3.5 Export & Manual Engraving Drawings

Configuration Import/Export (JSON);
Point Map Import/Export (PNG / SVG, points as <circle />);
Trajectory Export (SVG <path />, can include occlusion information);
Manual Engraving Drawing Generation Mode:
- Up to 64 layers of drawings;
- Export folder containing multiple SVGs + HTML;
- HTML uses TEMPLATE.html template, can be modified for layout.

4. Scratch Trajectory Generation Principle (Brief Explanation)

This section provides an overview of the underlying algorithm for secondary development or self-verification.

4.1 From Depth to Curve "Curvature"

Given a depth map depthImage, for each sampling point $(x, y)$ :

Normalized Height
Using a baseline height zeroHeight as 0:
$depth = depthImage(y, x) - zeroHeight$
Map Height to Curvature
Map depth to the image width range:
$curvature = \frac{depth \times imageWidth}{bFactor}$
- Positive depth: trajectory bends in one direction (e.g., "protruding");
- Negative depth: bends in the opposite direction ("recessed").
Center Offset Compensation
To ensure the curve's midpoint is near the original sampling point, introduce an offset based on $t = 0.5$ :
$offset = \frac{(1 + 3 \times aFactor)\times curvature}{4}$

4.2 Cubic Bézier Control Point Construction

On the image plane, at the compensated center point:

\mathbf{C} = \begin{bmatrix} x \\ y \end{bmatrix} + \begin{bmatrix} 0 \\ offset \end{bmatrix}

Construct start point, end point, and two control points:

\mathbf{P_0} = C + curvature \cdot \begin{bmatrix} -1 \\ -1 \end{bmatrix}, \quad \mathbf{P_3} = C + curvature \cdot \begin{bmatrix} 1 \\ -1 \end{bmatrix}

\mathbf{P_1} = C + curvature \cdot \begin{bmatrix} -1 \\ -1 \end{bmatrix} \cdot aFactor, \quad \mathbf{P_2} = C + curvature \cdot \begin{bmatrix} 1 \\ -1 \end{bmatrix} \cdot aFactor

4.3 Cubic Bézier Curve

Finally, a scratch segment is represented by a cubic Bézier curve:

\mathbf{P}(t) = (1-t)^3\mathbf{P_0} + 3(1-t)^2 t\mathbf{P_1} + 3(1-t)t^2\mathbf{P_2} + t^3\mathbf{P_3},\quad t\in[0,1]

$t=0$ is the start point $P_0$ ;
$t=1$ is the end point $P_3$ ;
$P_1, P_2$ control the bending shape, with aFactor and other parameters adjusting the overall curvature.

4.4 SVG Path Generation & Occlusion Splitting

Basic Path Generation

Each sampling point generates a Bézier curve command and is concatenated into the same SVG <path>:
```
<path d="M P0.x,P0.y C P1.x,P1.y P2.x,P2.y P3.x,P3.y ..." />
```
Occlusion Handling (v2.0)
- Sample each curve from multiple viewing angles;
- Use the depth map to compare front-back occlusion;
- When a segment falls behind an occluding object, split the corresponding Bézier segment and discard the hidden part;
- The final exported path only retains the "visible" scratch parts.

5. FAQ & Tips

Q: Can I use it without downloading the ONNX model? A: Yes, but the prerequisite is that you provide the depth map yourself. Without a depth map, the software cannot generate 3D trajectories.
Q: What's the difference between SVG point maps and SVG trajectories?
SVG Point Map: Each point is a <circle />, used for saving/editing sampling points;
SVG Trajectory: Uses <path /> to describe actual scratch trajectories, used for actual machining or simulation.
Q: Can the 3D preview export images? Currently not; it's only for interactive stereoscopic preview.
Q: Multi-language support? Starting from v1.6.1, supports Simplified Chinese, Traditional Chinese, English, Japanese, French, Russian, German, and more (initial machine translation version).

Download: 👉 Latest windows_anycpu release version
This project is open source under the Apache-2.0 License. You are welcome to modify it or integrate it into your pipeline under the terms of the license.