# Pli — gói chuyển giao Blender, phiên bản 1.0.0

Một nghiên cứu nguyên bản của RenderParcel: lọ gốm màu tím, cổ áo màu cam satin, nhãn hình chevron trên giấy và đế bằng đất sét. Khung hình được bố trí cho một ảnh sản phẩm với vùng trống ở bên trái. Đây không phải là vật thể của khách hàng cũng không phải mô hình được tái tạo từ ảnh chụp.

## Nội dung thực sự của gói tải xuống

Gói này cung cấp một **trình tạo cảnh**, một texture nguyên bản, một công thức và các kiểm soát. Không có tệp `.blend` nào hay bản render Blender nào được tạo ra trong môi trường chuẩn bị: Blender không được tìm thấy ở đó. Việc xác thực đã thực hiện chỉ áp dụng cho các tệp, đường dẫn, PNG, cú pháp Python và lỗi phụ thuộc. Đọc `VALIDATION.md`.

Mục tiêu tái tạo là **Blender 4.5.x LTS**, cùng Python tích hợp và Cycles. Script từ chối nhánh khác để tránh biến một khả năng tương thích giả định thành một bài kiểm tra. Không yêu cầu module Python bên ngoài, tiện ích mở rộng Blender, phông chữ, HDRI hay mô hình nào. Một Python 3.10+ độc lập là đủ để kiểm tra gói; các bài kiểm tra đi kèm đã được chạy với Python 3.14.6 trên Windows.

## Cấu trúc thư mục và điểm vào

```text
blender-v1/
  README.md, LICENSE.txt, VALIDATION.md
  scene.json                    công thức, phiên bản, phụ thuộc và đầu ra
  manifest.sha256.json           kích thước và SHA-256 của các tệp được phân phối
  generate_scene.py              điểm vào cần chạy TRONG Blender
  inspect_scene.py               mở để kiểm tra trong một Blender thứ hai
  validate_pack.py               kiểm tra tệp KHÔNG cần Blender
  01_sources/make_texture.py     công thức gốc của PNG
  02_projet/                    nhận tệp .blend được tái tạo
  03_ressources/pli-chevron.png  texture sRGB cần giữ nguyên
  04_caches/                    không có cache cho cảnh tĩnh này
  05_rendus/                    nhận bản xem trước CPU nếu được yêu cầu
  06_livraison/                 phiếu tiếp nhận và báo cáo sau khi chạy
```

Manifest bao gồm các tệp được phân phối, ngoại trừ chính nó để tránh một dấu vân tay vòng. Các đầu ra được tạo sau đó không thuộc manifest này. Một dấu vân tay phát hiện sự khác biệt của tệp; nó không chứng nhận nguồn gốc hay hình thức của tệp. Đối với gói chuyển giao của riêng bạn, hãy tạo một bản kiểm kê mới có ghi ngày bao gồm các đầu ra đã được phê duyệt.

## 1. Giải nén và xác thực trước khi mở Blender

Giải nén ZIP vào một thư mục mới, rồi mở terminal tại thư mục gốc `blender-v1`. Không chạy bất kỳ lệnh nào từ bên trong một tệp lưu trữ còn đang nén.

```sh
python validate_pack.py --root . --json
```

Kết quả phải chứa `"ok": true` và mã thoát phải là 0. Một tệp bị thiếu, bị thay đổi, nằm ngoài thư mục hoặc một PNG không hợp lệ sẽ gây thất bại (mã 1). Dừng lại ở đây nếu kiểm tra thất bại. Không viết lại manifest chỉ để che giấu một lỗi.

Trên Windows, `py -3` có thể thay thế `python`. `blender` bên dưới phải chỉ tệp thực thi Blender 4.5.x của bạn; nếu thư mục của nó không nằm trong PATH, hãy dùng đường dẫn đầy đủ của nó trong dấu ngoặc kép (với `&` trước đường dẫn đó trong PowerShell).

## 2. Tái tạo trong một tiến trình Blender riêng

Script tạo lại một cảnh trống trong bộ nhớ; đừng chạy nó trong một dự án chưa được lưu. Từ thư mục đã giải nén:

```sh
blender --background --factory-startup --python-exit-code 1 --python generate_scene.py -- --render-preview
```

Lệnh này phải tạo ra:

- `02_projet/renderparcel_pli_v1.blend`: cảnh tĩnh, ảnh 1, camera `Pli_Camera`, Cycles CPU, 1 200 × 750 pixel và 64 mẫu;
- `05_rendus/pli_controle_cpu.png`: **nếu render thành công**, bản xem trước CPU 480 × 300 pixel, 16 mẫu, không khử nhiễu;
- `06_livraison/reconstruction.json`: phiên bản Blender thực sự được dùng, các đối tượng, thiết bị được chọn và trạng thái thực tế của render.

Bỏ `-- --render-preview` để chỉ tạo tệp `.blend`. Báo cáo khi đó sẽ ghi `renderExecuted: false`. Script lưu cảnh theo định nghĩa làm việc của nó trước khi tính toán rút gọn; do đó tệp `.blend` không bị thay thế bằng các thiết lập xem trước. Các lệnh không bao giờ khởi động GPU.

Các đầu ra đã tồn tại sẽ bị từ chối. Để thử lại, hãy giải nén lại gói vào một thư mục khác, thay vì ghi đè lên một kết quả đã được giữ lại. Một ngoại lệ được báo cho hệ thống bằng `--python-exit-code 1`; hãy giữ lại các thông báo của terminal trong trường hợp thất bại.

## 3. Mở lại scene trong một tiến trình thứ hai

```sh
blender --background --factory-startup --python-exit-code 1 --python inspect_scene.py
```

Bước kiểm tra sẽ mở file `.blend` mà không chạy các script nội bộ của nó, xác minh mười đối tượng, camera, Cycles CPU, các thiết lập, phạm vi một khung hình, AgX, texture được nhúng và đường dẫn tương đối của nó. Kết quả được ghi vào `06_livraison/inspection-blender.json`. Bước kiểm tra này không đánh giá vẻ đẹp của hình ảnh và không thay thế việc tự xem xét hình ảnh.

Sau đó mở file PNG bằng một trình xem ảnh. **Sao chép** `06_livraison/modele-reception.csv` sang một file mới `06_livraison/reception-executee.csv`, rồi điền vào bản sao này: toàn bộ lọ nằm trong khung hình, họa tiết kem/tím/cam trên mặt trước, tiếp xúc với đế, không có texture màu magenta, các điểm phản chiếu rõ ràng. Mẫu gốc giữ nguyên không đổi để bảo toàn dấu vân tay của nó; bản sao đã điền là một đầu ra cần được kiểm kê trong gói bàn giao của riêng bạn. Những tiêu chí này là những ý định cần kiểm chứng sau khi dựng lại; không có bản render đối chứng nào từ Blender được kèm trong phiên bản phát hành.

## 4. Kiểm tra việc chuyển giao mà không có các tài nguyên cũ

Sao chép **toàn bộ thư mục đã dựng lại** sang máy đích hoặc vào một môi trường mà các đường dẫn của máy trạm sáng tạo không thể truy cập được. Chạy bước kiểm tra file rồi mở bản sao của `.blend`. Chỉ di chuyển đơn thuần trên cùng một máy là không đủ nếu các đường dẫn tuyệt đối cũ vẫn còn dùng được.

Texture bên ngoài được giữ trong `03_ressources`. Trong file `.blend`, đường dẫn dự kiến là `//../03_ressources/pli-chevron.png`, vì `//` là tương đối so với file Blender nằm trong `02_projet`. Trình tạo nạp texture rồi nhúng nó qua `Image.pack()` trước khi lưu. Hai hình thức này cho phép chỉnh sửa nguồn trong khi vẫn kiểm soát được việc nhúng; sau khi chỉnh sửa, hãy nạp lại/nhúng lại và lưu phiên bản được chọn.

Với một dự án đã có sẵn: lưu vào thư mục đích; dùng File → External Data → Make Paths Relative; chạy Report Missing Files. Find Missing Files có thể sửa các liên kết nhưng lại biến chúng thành tuyệt đối: hãy kiểm tra lại chúng. Pack Resources không chứa toàn bộ dữ liệu bên ngoài, đặc biệt là video. Các thư viện được liên kết cần quy trình riêng; gói này không dùng thư viện nào như vậy.

## 5. Điều chỉnh công thức cho dự án của bạn

Hãy bắt đầu bằng một bản sao riêng biệt, vì mọi thay đổi đối với nguồn đều làm mất hiệu lực bản kê khai gốc. Giữ phần mềm/phiên bản, camera, scene, engine, độ phân giải, số mẫu, biến đổi hiển thị, texture, tiện ích mở rộng và đích của các đầu ra trong một bản kiểm kê riêng. File PNG của gói là một màu cơ sở sRGB, không phải map pháp tuyến hay map dịch chuyển.

Scene này **không dùng bất kỳ animation nào, không có cache mô phỏng, không có âm thanh, không có phông chữ cũng không có thư viện được liên kết**. Nếu bạn thêm khói, vải hay hình học động, hãy kiểm kê loại cache, vị trí của nó, toàn bộ phạm vi và quy trình tính toán trước. Đóng băng cache trước khi sao chép chúng. Kiểm tra các khung hình trung gian và từng file trong chuỗi: một khung hình 1 đúng không xác nhận được cả một animation.

Dung lượng của file ZIP không đo được VRAM khi render. Một bản xem trước CPU thu gọn không cho phép ước lượng thời gian GPU. Để tính toán quy mô sản xuất của bạn, hãy đo scene đầy đủ ở độ phân giải cuối cùng và kiểm tra mức đỉnh bộ nhớ với một khoảng dự phòng cho các bước khắt khe của nó. Giữ một bản sao lưu độc lập cho đến khi nghiệm thu.

## Dựng lại texture, tùy chọn

```sh
python 01_sources/make_texture.py --output 05_rendus/motif-reconstruit.png
```

Việc tính toán họa tiết là tất định và chỉ dùng các phép toán số nguyên. Trong các bài kiểm thử đã công bố, các byte PNG dựng lại khớp với file được bàn giao khi dùng cùng một thư viện zlib. Giữa các phiên bản nén khác nhau, hãy so sánh cả các pixel thay vì giả định các byte nén là giống hệt nhau.

## Nguồn của quy trình

- [Hướng dẫn Blender 4.5, dữ liệu nhúng](https://docs.blender.org/manual/sr/4.5/files/blend/packed_data.html) : phạm vi của Pack Resources, lưu và thư viện liên kết.
- [Hướng dẫn Blender 4.5, External Data](https://docs.blender.org/manual/ja/4.5/interface/window_system/topbar.html) : đường dẫn tương đối và tìm kiếm tệp bị thiếu.
- [API Blender 4.5, Wm Operators](https://docs.blender.org/api/4.5/bpy.ops.wm.html) : lưu và mở với script nội bộ bị vô hiệu hóa.
- [API Blender 4.0, Image](https://docs.blender.org/api/4.0/bpy.types.Image.html) : ảnh bên ngoài/nhúng và thao tác `pack` ; tài liệu tham chiếu có thể truy cập đã được xem, trang 4.5 không truy cập được trong quá trình chuẩn bị này.
- [Hướng dẫn Blender 4.5, dòng lệnh](https://docs.blender.org/manual/es/4.5/advanced/command_line/arguments.html) : thực thi script và mã thoát Python.
- [Hướng dẫn Blender 4.5, quản lý màu](https://docs.blender.org/manual/sr/4.5/render/color_management.html) : diễn giải texture và chuyển đổi hiển thị.
- [Hướng dẫn Blender 4.5, tính toán trước](https://docs.blender.org/manual/fr/4.5/physics/baking.html) : xử lý riêng biệt các bộ nhớ đệm và phạm vi mô phỏng.

Các bản dịch chính thức được sử dụng khi trang tiếng Anh không phản hồi. Chúng ghi lại các thao tác, mà không thay thế việc thử nghiệm Blender vẫn cần phải thực hiện. Các liên kết thương mại và lựa chọn GPU nằm trong hướng dẫn RenderParcel, không nằm trong công thức kỹ thuật.

## Khả năng tương thích với các thư mục trước đó

Các bản dựng lại mới lưu `02_projet/renderparcel_pli_v1.blend`. Không tệp nào đã tạo trước đó bị di chuyển hay đổi tên. Nếu đầu ra mới này không có, `inspect_scene.py` vẫn có thể mở `02_projet/prismora_pli_v1.blend`, tên đầu ra cũ. Nếu cả hai tệp đều tồn tại, quá trình kiểm tra sẽ chọn đầu ra mới.

Các định danh schema `prismora.blender-transfer.v1` và `prismora.integrity.v1`, các thuộc tính kỹ thuật `prismora_pack_version` và `prismora_purpose`, cùng tên module nội bộ `prismora_validator`, vẫn ổn định để đọc các thư mục v1. Đây là những khóa tương thích, không phải thương hiệu hiển thị của thư mục.