🧱 Script FreeCAD Voxelizer – Biến mọi STL thành gạch!

(Mô tả tiếng Đức bên dưới / German description below)

🇬🇧 English Description

Script Python này cho FreeCAD giúp bạn chuyển đổi bất kỳ file STL nào thành một tác phẩm Voxel-Art kiểu pixel hoặc một mẫu “Building Block” (phong cách Lego).

Khác với các voxelizer thông thường, script này dùng cách streaming STL nhị phân (binary) tuỳ biến. Nhờ vậy nó né được giới hạn bộ nhớ nội bộ của FreeCAD, cho phép tạo model cực lớn (100k+ bricks) ngay cả trên laptop 8GB RAM mà không bị crash.

✨ Tính năng nổi bật

• Hiệu năng cao: Ghi dữ liệu STL nhị phân thẳng ra ổ đĩa. Không bị nghẽn RAM.

• Watertight Geometry: Tạo hình học kín hoàn toàn (gạch đã merge + studs đặc) giúp slicer xử lý “ngon” (0 open edges).

• Greedy Meshing: Thuật toán thông minh gộp các voxel đơn lẻ thành gạch lớn hơn (ví dụ gộp bốn khối 1x1 thành một gạch 1x4) để in nhanh hơn và chắc hơn.

• Hollow Shell: Chỉ voxelize phần bề mặt của model để tiết kiệm filament.

• Brick Mode: Tự động đặt studs (knobs) lên mặt trên của các viên gạch đang lộ ra.

🚀 Cách dùng (Workflow)

1. Tải file script .py trong mục files.

2. Mở FreeCAD (khuyến nghị Version 0.20 trở lên).

3. Import file STL vào FreeCAD (File -> Import...).

4. Mở Macro Manager: Macro -> Macros....

5. Bấm Create, dán code script vào và lưu lại (ví dụ đặt tên “LegoVoxelizer”).

• Hoặc: Copy file .py đã tải về vào thẳng thư mục FreeCAD Macros của bạn.

6. Chọn macro trong danh sách rồi bấm Execute.

7. Xong! File kết quả WatertightLego_...stl sẽ được lưu trong thư mục Output mới, nằm cùng thư mục với nơi bạn lưu file macro.

⚙ Cấu hình (Tuning)

Ngay đầu script, bạn có thể chỉnh dictionary CONFIG để thay đổi “look” của model:

• target_voxel_count: Số lượng bricks mục tiêu. Thấp (vd 5000) = nhìn khối/abstract hơn. Cao (vd 50000) = chi tiết hơn.

• min_voxel_size_mm: Kích thước cạnh tối thiểu của một block (mm).

• lego_mode_enabled: Đặt True để có studs, False để ra khối trơn (kiểu Minecraft).

• merge_bricks: Đặt True để gộp các block nhỏ thành gạch dài (rất nên bật!).

• gap_size_mm: Khe hở giữa các viên gạch (vd 0.08mm). Đặt 0 để thành tường đặc.

⚠ Mẹo khi in

• Scale: Nếu muốn kích thước gạch Lego “ngoài đời” (8mm), bạn cần scale model STL lên 3–5x trước khi chạy script, nếu không sẽ chỉ ra được vài block.

• Infill: Thường 10–15% là đủ.

• Supports: Đa số không cần vì dạng khối (overhang thường là 90°, máy in xử lý ổn).

🇩🇪 Deutsche Beschreibung

Script Python này cho FreeCAD biến bất kỳ STL nào thành một tượng voxel hoặc một model dạng gạch lắp ráp.

Khác với voxelizer thông thường, script này dùng binary STL stream trực tiếp. Cách này bỏ qua hoàn toàn giới hạn bộ nhớ của FreeCAD và cho phép tạo model rất lớn (hơn 100.000 viên), ngay cả trên laptop ít RAM mà không bị treo.

✨ Chức năng chính

• High Performance: Ghi dữ liệu thẳng ra ổ đĩa. Không bị giới hạn RAM.

• Watertight (kín nước): Tạo hình học kín (đáy, nắp, noppen/studs), để slicer không báo “Open Edges”.

• Greedy Meshing: Thuật toán thông minh gộp voxel thành viên gạch lớn (vd bốn 1x1 thành một 1x4). Giúp giảm thời gian in và nhìn “thật” hơn.

• Hollow Shell: Chỉ voxelize phần bề mặt (“Shell”) để tiết kiệm filament.

• Lego-Modus: Tự đặt studs lên các mặt trên đang lộ ra.

🚀 Hướng dẫn (Workflow)

1. Tải script .py trong phần file.

2. Mở FreeCAD (khuyến nghị 0.20 trở lên).

3. Import STL vào FreeCAD (Datei -> Importieren...).

4. Mở Macro Manager: Makro -> Makros....

5. Bấm Erstellen, dán code và lưu lại (vd “LegoVoxelizer”).

• Hoặc: Copy file .py tải về vào thư mục macro của FreeCAD.

6. Chọn macro trong danh sách và bấm Ausführen.

7. Xong! Kết quả nằm trong thư mục Output mới, ở cùng thư mục với nơi lưu file macro.

⚙ Thiết lập (Config)

Ở đầu script có phần CONFIG để tuỳ chỉnh kết quả:

• target_voxel_count: Số lượng viên. Ít (vd 5000) = nhìn khối hơn. Nhiều (vd 50000) = chi tiết hơn.

• min_voxel_size_mm: Kích thước tối thiểu của một viên (mm).

• lego_mode_enabled: True có studs, False ra khối trơn (phong cách Minecraft).

• merge_bricks: True bật gộp gạch (khuyến nghị!).

• gap_size_mm: Khe giữa các viên (vd 0.08mm).

⚠ Mẹo in

• Skalierung (Scale): Nếu muốn đúng size Lego (gạch 8mm), bạn phải phóng to model STL lên 3–5 lần trước khi chạy script.

• Infill: 10–15% thường là quá ổn.

• Supports: Thường không cần do hình khối (bridge hoạt động tốt).

Credits:

Developed with the help of an AI Co-Pilot to solve memory constraint issues in FreeCAD.