Mosaic Lite - Hướng dẫn sử dụng

Tổng quan giao diện

Ảnh dưới là toàn bộ các trạng thái của app. Mọi ảnh trong hướng dẫn chụp từ app thật; ảnh khách là hình vẽ giả để minh hoạ.

Artboard giao diện Mosaic Lite: 6 trạng thái và chú thích các vùng

1. Chuẩn bị (làm 1 lần)

Thư mục	Dùng để	Gợi ý
Hot Folder	Phần mềm chụp / máy ảnh ghi ảnh vào đây	`D:\Dev\mosaic\HotFolder`
Cell Mosaic	~450 file `RxC.png` (hàng × cột) lấy từ MosaicDigital	`...\MosaicDigital\Sessions\VAECO\SeparateOverlayImage` (chỉ đọc)
Output (Prints)	Trang A6 xuất ra, phần mềm in theo dõi thư mục này	`D:\Dev\mosaic\Prints`

Hot Folder và Output phải khác nhau. App chỉ đọc thư mục Cell, không ghi vào đó.

2. Chạy app

Mở run.bat (giao diện) hoặc run_cli.bat (dòng lệnh).
Tab Chạy: bấm Chọn… cho 3 thư mục. Cạnh Cell Mosaic phải hiện Cells: 450.
Giữ Độ mờ overlay = 75 % (đúng với MosaicDigital).
Bấm ▶ Start. Trạng thái chuyển Đang chạy, các ô cấu hình bị khoá.
Mỗi ảnh mới vào Hot Folder: app chờ file ghi xong, xử lý, ghi một dòng log và hiện preview trang A6 mới nhất (khoảng 2 – 3 giây).

Đang chạy: log từng ảnh và preview trang A6

Thanh trạng thái: Đã xử lý (số ảnh đã ra file A6) và Lỗi (số ảnh thất bại).

3. In và cắt

Phần mềm in theo dõi thư mục Prints, in A6 dọc, 100 %, Actual size. Không chọn Fit to page.
Cắt theo vạch ở 4 góc ảnh để ra đúng 10 × 10 cm.

Trang A6 mẫu — Trang A6 1240 × 1748 px, 300 DPI: ảnh 10 × 10 cm ở giữa

Góc trên-trái phóng to: vạch dọc là vạch chính

4. Tab Tường: xem tổng thể và ghép lại từng ô

Tab Tường hiện cả bức tường 30 cột × 15 hàng, vừa khít cửa sổ. Ô viền xanh đã có ảnh khách.

Tab Tường: lưới 450 ô, ô viền xanh đã ghép, bảng chi tiết bên phải

Ghép lại một ô bằng ảnh khác

Bấm vào ô trên lưới. Bảng bên phải hiện tên ô (ví dụ R6 × C29) và trạng thái.
Bấm Chọn ảnh chụp để ghép vào ô này…, chọn ảnh jpg hoặc png.
App ghép đúng cell đó (không random) và lưu trang A6 vào Prints với tên <tên ảnh>__<hàng>x<cột>.jpg.
Xuất ảnh tổng thể tường… lưu wall_overview.jpg (3000 × 1500) vào Prints.

Ảnh từ Hot Folder cũng được ghi vào tường. Khi random, app ưu tiên ô chưa dùng; hết 450 ô mới quay lại từ đầu.

5. Các lỗi thường gặp và cách xử lý

Bấm vào từng mục để xem nguyên nhân và cách xử lý.

5.1 Báo “Hot folder không tồn tại” khi bấm Start

Hộp thoại báo lỗi cấu hình khi bấm Start

Nguyên nhân: Gõ sai đường dẫn, thư mục bị xoá, ổ đĩa hoặc USB chưa gắn.

Cách xử lý: Bấm Chọn… chọn lại thư mục (hoặc tạo thư mục rồi Start lại). Cùng kiểu lỗi cấu hình: thư mục Cell không tồn tại hoặc không có file .png, Hot Folder trùng Output.

5.2 Cạnh Cell Mosaic không hiện “Cells: 450”

Nguyên nhân: Trỏ nhầm thư mục (ví dụ thư mục cha) hoặc chưa copy cell vào.

Cách xử lý: Trỏ đúng thư mục chứa trực tiếp các file RxC.png. App chỉ đếm file .png ngay trong thư mục đó, không đếm thư mục con.

5.3 Ảnh ra bị phủ màu backdrop, gần như không thấy khách

Nguyên nhân: Độ mờ overlay đặt quá cao (100 %). Cell là tile đặc nên che hết ảnh chụp. App ghi cảnh báo (dòng cam) khi Start.

Cách xử lý: Đặt Độ mờ overlay = 75 % rồi Start lại. Nếu máy có config.json cũ lưu 100 % thì cũng phải sửa ô này trước khi Start.

5.4 Chụp xong nhưng không có file trong Prints

Nguyên nhân: Một trong các nguyên nhân sau.

Cách xử lý:

Trạng thái phải là Đang chạy (không phải Đã dừng).
Phần mềm chụp phải ghi đúng Hot Folder (xem dòng đầu của log).
Chỉ xử lý .jpg, .jpeg, .png. File .tmp hoặc tên bắt đầu bằng ~ bị bỏ qua.
Ảnh đã xử lý (cùng tên, kích thước, giờ sửa) không bị xử lý lại, kể cả sau khi mở lại app. Muốn xử lý lại thì chụp lại hoặc ghi đè ảnh.
Chờ 3 – 5 giây nếu phần mềm chụp ghi file chậm.

5.5 Dòng đỏ ERROR “thất bại” trong log, bộ đếm Lỗi tăng

Một ảnh hỏng: hai dòng cam rồi một dòng đỏ, Lỗi = 1

Nguyên nhân: File không phải ảnh hợp lệ hoặc bị hỏng. App thử lại 2 lần (hai dòng cam WARNING) rồi báo lỗi.

Cách xử lý: Chụp lại tấm đó, các ảnh khác không bị ảnh hưởng. Nếu mọi ảnh đều lỗi, kiểm tra dung lượng ổ đĩa và quyền ghi vào Prints.

5.6 Có dòng ERROR “truncated” nhưng ảnh vẫn ra đủ

Nguyên nhân: Phần mềm chụp ngừng ghi file hơn 1 giây rồi ghi tiếp. App thử bản dở, báo lỗi một lần, rồi tự xử lý lại khi file ghi xong.

Cách xử lý: Không cần làm gì. Kiểm tra trong Prints chỉ có 1 file cho ảnh đó. Chỉ khi lặp lại với mọi ảnh thì đổi cách xuất của phần mềm chụp (ghi file tạm .tmp rồi đổi tên khi xong).

5.7 Ảnh in mất mép hoặc không đủ 10 × 10 cm

Nguyên nhân: Máy in ảnh dùng giấy 4×6″ (101,6 mm) hẹp hơn A6 (105 mm). In Fit thì ảnh co còn khoảng 96,8 mm, in 100 % thì mất khoảng 1,7 mm mỗi bên. Lề hai bên chỉ 2,5 mm nên vạch ngang có thể bị máy in cắt mất.

Cách xử lý: Dùng giấy A6 thật, in 100 % / Actual size. Cắt theo vạch dọc (dài, ở lề trên và dưới). In thử 1 tờ và đo ảnh bằng thước trước khi chạy sự kiện.

5.8 Giao diện chậm khi nhiều ảnh dồn dập

Nguyên nhân: Hàng trăm ảnh vào cùng lúc thì app xử lý lần lượt từng ảnh; log chỉ giữ 500 dòng cuối.

Cách xử lý: Chờ hàng đợi hết, không tắt app. Nếu cần bấm Stop rồi Start: ảnh đã xử lý không bị xử lý lại.

5.9 Tab Tường báo “Đang nạp…” lâu hoặc lưới trống

Nguyên nhân: Lần đầu nạp 450 cell mất khoảng 6 giây (có cache nên các lần sau khoảng 1 giây). Lưới trống khi thư mục Cell Mosaic trống hoặc sai.

Cách xử lý: Chọn đúng thư mục ở tab Chạy, rồi bấm Nạp lại ở tab Tường.

5.10 Chọn ảnh ở tab Tường báo lỗi

Nguyên nhân: Ảnh hỏng, hoặc thư mục Output không tồn tại hay không ghi được.

Cách xử lý: Thử ảnh khác; kiểm tra Output ở tab Chạy (nút Mở thư mục). Ghép đè lên ô đã có ảnh luôn hỏi xác nhận trước.

5.11 Mở run.bat không lên cửa sổ

Nguyên nhân: Máy chưa cài Python 3.12 hoặc thiếu trong PATH. Hiếm khi Tk khởi tạo lỗi ngẫu nhiên.

Cách xử lý: Mở cmd, chạy python -m mosaic_lite --gui để xem thông báo lỗi. Nếu không có lỗi mà vẫn không lên: tắt hẳn app và mở lại.

6. Tạo ảnh chụp thử bằng Gemini

Dùng để thử luồng trước khi có ảnh thật. App cắt vuông chính giữa ảnh nên chủ thể phải nằm giữa khung.

Prompt gốc (thay [NGƯỜI/CẢNH] bằng một dòng bên dưới)

Tạo một ảnh chụp chân thực như chụp bằng máy ảnh DSLR tại sự kiện doanh nghiệp, tỷ lệ 3:2 ngang, độ phân giải cao, ánh sáng studio mềm, nền sáng đơn giản.
Chủ thể: [NGƯỜI/CẢNH].
Yêu cầu bố cục: toàn bộ khuôn mặt và phần thân trên nằm gọn trong vùng vuông chính giữa khung hình (chiếm khoảng 60% chiều cao, cách mép trái và phải ít nhất 20% chiều rộng), nhìn thẳng vào ống kính, nụ cười tự nhiên, mắt mở rõ.
Không chữ, không logo, không watermark, không khung viền, không chồng ảnh. Không có thêm người nào bị cắt ở mép ảnh.
Màu da và ánh sáng tự nhiên, độ sắc nét cao, bokeh nhẹ ở nền.

12 mô tả để thay vào

một nhân viên nam Việt Nam khoảng 30 tuổi, áo sơ mi xanh nhạt, cười tươi
một nữ nhân viên khoảng 28 tuổi, áo vest đen, tóc dài, đang giơ ngón cái
hai đồng nghiệp (nam và nữ) đứng sát vai nhau, cùng cười, đồng phục công ty màu xanh dương
một kỹ sư bảo dưỡng máy bay nam, áo bảo hộ cam, đội mũ cứng trắng, cười rạng rỡ
một nữ quản lý trung niên, áo dài hiện đại màu vàng nhạt, mỉm cười thân thiện
ba nhân viên đứng thành hàng, vòng tay qua vai nhau, vui vẻ
một nam giám đốc khoảng 45 tuổi, vest xám, tay chỉnh cà vạt, tự tin
một cô gái trẻ, áo sơ mi trắng, cầm một mô hình máy bay nhỏ, cười
nhóm bốn người, hai nam hai nữ, đồng phục, giơ tay chữ V
một kỹ thuật viên nữ, áo bảo hộ xanh, tóc buộc đuôi ngựa, cười
một nam nhân viên trẻ đeo kính, áo polo xanh navy, vẫy tay chào
một cặp vợ chồng trung niên mặc trang phục công sở, cười hạnh phúc

Ảnh Gemini thường chỉ 1 – 2 MP nên kém nét hơn ảnh máy ảnh khi in 10 × 10 cm. Chỉ dùng để thử luồng, không dùng để đánh giá chất lượng in. Thả ảnh vào Hot Folder, trang A6 sẽ ra trong Prints.

7. Kiểm tra nhanh trước giờ G (5 phút)

Chụp thử 3 – 5 tấm liên tiếp bằng đúng phần mềm chụp của sự kiện.
Mỗi tấm ra đúng 1 file A6 trong Prints sau 2 – 3 giây, không dòng đỏ.
In thử 1 tờ, đo ảnh 10 × 10 cm, cắt thử theo vạch.
So màu với một trang MosaicDigital cùng cell (độ mờ 75 %).
Mở tab Tường, kiểm tra “Đã ghép N / 450” khớp số ảnh đã chụp.

8. Dòng lệnh (tuỳ chọn)

python -m mosaic_lite --hot D:\Dev\mosaic\HotFolder --cells "C:\...\SeparateOverlayImage" --out D:\Dev\mosaic\Prints --opacity 0.75

--once xử lý ảnh đang có rồi thoát; --seed N để chọn cell lặp lại được; --png xuất thêm PNG.