Hướng dẫn RuiC-PoseAtlas: Xây dựng và sử dụng thư viện tham khảo tư thế người đa ngôn ngữ

Giới thiệu RuiC-PoseAtlas

RuiC-PoseAtlas là thư viện tham khảo tư thế người hoàn toàn tĩnh, không có phụ thuộc thời gian chạy. Dự án bao gồm 288 nhóm tư thế và 1.439 bản vẽ đường nét hình nhân, tập hợp các góc nhìn chính diện, chếch, bên hông, từ trên xuống và từ dưới lên của cùng một tư thế, giúp nhà sáng tạo dễ dàng so sánh liên tục dáng người, tỷ lệ, hướng của tay chân và mối quan hệ với góc máy.

Thư viện phù hợp cho AI vẽ, minh họa, truyện tranh, dựng hình 3D, hoạt hình, bố cục nhiếp ảnh và thiết kế thị giác, đồng thời có thể dùng làm ví dụ học tập cho dự án frontend nguyên bản. Website được viết bằng HTML, CSS và ES Modules thuần, không phụ thuộc React, Vue hay trình đóng gói.

Lưu ý nội dung: Dự án dành cho nhà sáng tạo trưởng thành; một số nội dung không phù hợp với người chưa thành niên. Khi sử dụng, hãy tuân thủ luật pháp nơi bạn sinh sống và quy định của nền tảng.

Nếu chỉ muốn xem trực tiếp, hãy mở bản demo trực tuyến RuiC-PoseAtlas. Khi cần nghiên cứu mã nguồn, tùy chỉnh dữ liệu hoặc tự triển khai, hãy làm theo các bước tiếp theo để sao chép kho lưu trữ.

Tính năng chính

• Đối chiếu nhiều góc nhìn: Mỗi nhóm tư thế gồm 4 đến 5 góc nhìn, có thể chuyển đổi trong thẻ hoặc trang ảnh lớn.
• Hai chế độ duyệt: “Theo tư thế” nhóm các góc nhìn cùng nhóm, còn chế độ “Từng ảnh” hiển thị từng góc nhìn riêng.
• Bộ lọc kết hợp: Có thể lọc theo series, danh mục và góc nhìn; dự án bao gồm 4 series nội dung và 26 danh mục con.
• Tìm kiếm đa ngôn ngữ: Tên tiếng Trung, tiếng Anh và tiếng Nhật được lập chỉ mục đồng thời; cũng có thể tìm theo mã tư thế, danh mục và series.
• Giao diện ba ngôn ngữ: Hỗ trợ chuyển đổi tức thì giữa 中文, English và 日本語, đồng thời lưu lựa chọn vào localStorage.
• Điều khiển bằng bàn phím: Phím mũi tên dùng để chuyển góc nhìn và tư thế, Esc dùng để đóng ảnh lớn.
• Tải ảnh gốc: Trang ảnh lớn cung cấp tệp PNG kích thước 900 × 1200 để tải xuống.
• Liên kết sâu: Có thể chia sẻ trực tiếp ngôn ngữ, tư thế và góc nhìn cụ thể qua URL.
• Bố cục thích ứng: Hỗ trợ lưới nhiều cột trên máy tính, thẻ hai cột trên thiết bị di động và xem ảnh lớn trên màn hình hẹp.
• Kiểm tra kỹ thuật: npm run verify có thể kiểm tra dữ liệu, bản dịch, tham chiếu tệp, kích thước ảnh và khóa i18n.

Chuẩn bị môi trường chạy

Để duyệt hằng ngày, bạn chỉ cần trình duyệt hiện đại và một máy chủ HTTP tĩnh. README khuyến nghị sử dụng Python 3; nếu cần tạo lại dữ liệu, khôi phục ảnh hoặc thực hiện kiểm tra toàn vẹn, bạn cũng cần Node.js 18 trở lên.

• Trình duyệt hiện đại như Chrome, Edge, Safari hoặc Firefox
• Python 3 hoặc máy chủ tĩnh khác
• Node.js 18 trở lên, chỉ dùng cho các tác vụ script
• Đủ dung lượng ổ đĩa, vì ảnh PNG gốc chiếm khoảng 654 MB và ảnh thu nhỏ khoảng 25 MB

Cài đặt và khởi chạy cục bộ

Bước 1: Sao chép kho lưu trữ

git clone https://github.com/HRuiCcc/RuiC-PoseAtlas.git
cd RuiC-PoseAtlas

Kho lưu trữ bao gồm đầy đủ 1.439 ảnh PNG gốc và 1.439 ảnh thu nhỏ JPEG, vì vậy lần sao chép đầu tiên có thể mất một chút thời gian.

Bước 2: Khởi động máy chủ tĩnh

python3 -m http.server 8123 --bind 127.0.0.1

Sau đó truy cập bằng trình duyệt:

http://127.0.0.1:8123/

Nếu đã cài Node.js, bạn cũng có thể chạy trực tiếp lệnh do dự án cung cấp:

npm start

Không nhấp đúp trực tiếp vào index.html. Trang này đọc data/poses.json thông qua fetch(); dưới giao thức file://, yêu cầu có thể bị chính sách cùng nguồn của trình duyệt chặn, khiến trang hiển thị trống.

Cách sử dụng cơ bản

Tìm kiếm và lọc tư thế

1. Nhập tên tư thế bằng tiếng Trung, tiếng Anh hoặc tiếng Nhật vào ô tìm kiếm, hoặc nhập mã như P019.
2. Sử dụng các thẻ series ở đầu trang để thu hẹp phạm vi nội dung.
3. Tiếp tục chọn danh mục và góc nhìn để kết hợp nhiều điều kiện lọc.
4. Chuyển đổi giữa “Theo tư thế” và “Từng ảnh” để lần lượt so sánh nhóm tư thế hoặc lọc từng ảnh.
5. Trên thiết bị di động, nhấn “Bộ lọc” để mở bảng bộ lọc đang thu gọn.

Duyệt thẻ và ảnh lớn

Nhấp vào ảnh thu nhỏ góc nhìn ở cuối thẻ để xem trước góc nhìn tương ứng ngay trong thẻ; nhấp vào ảnh chính hoặc tiêu đề thẻ để mở ảnh lớn. Nếu chọn góc nhìn trong thẻ trước rồi nhấp vào ảnh chính, trang ảnh lớn sẽ bắt đầu hiển thị từ góc nhìn đó.

Trang ảnh lớn hỗ trợ các thao tác bàn phím sau:

• ← và →: Chuyển sang góc nhìn trước hoặc tiếp theo.
• ↑ và ↓: Chuyển sang tư thế trước hoặc tiếp theo.
• Esc: Đóng ảnh lớn.
• Tab: Di chuyển vòng qua các điều khiển trên trang ảnh lớn.

Trang cũng hiển thị tên tư thế, mã số, series, danh mục, góc nhìn hiện tại và thông số ảnh. Khi cần lưu tư liệu tham khảo, hãy nhấp vào “Tải ảnh gốc (PNG)”.

Chuyển ngôn ngữ và chia sẻ liên kết sâu

Có thể chuyển đổi giữa tiếng Trung, tiếng Anh và tiếng Nhật ở góc trên bên phải. Lựa chọn ngôn ngữ ưu tiên đọc tham số URL, tiếp theo là localStorage, cuối cùng dựa trên ngôn ngữ trình duyệt để quyết định giao diện mặc định.

http://127.0.0.1:8123/?lang=en
http://127.0.0.1:8123/?lang=ja#pose=full_single_P019&angle=side

Ví dụ thứ hai sẽ mở giao diện tiếng Nhật và định vị đến góc nhìn bên hông của full_single_P019. Sau khi triển khai trực tuyến, bạn cũng có thể sử dụng cùng tham số và cấu trúc hash để chia sẻ nội dung cụ thể.

Tìm hiểu cấu trúc dự án

Dự án áp dụng thiết kế hướng dữ liệu, trong đó data/poses.json là nguồn dữ liệu cốt lõi của thư viện. Bộ lọc, tìm kiếm, thẻ và trang ảnh lớn đều được tạo từ dữ liệu này.

RuiC-PoseAtlas/
├── index.html
├── assets/
│   ├── css/app.css
│   ├── js/app.js
│   └── js/i18n.js
├── data/poses.json
├── img/
├── thumbs/
├── scripts/
├── .github/workflows/
└── package.json

• assets/js/app.js: Phụ trách tải dữ liệu, tìm kiếm và lọc, kết xuất trang, tương tác ảnh lớn và phím tắt.
• assets/js/i18n.js: Lưu tập trung nội dung giao diện của ba ngôn ngữ.
• data/poses.json: Lưu 288 nhóm tư thế, tên bằng ba ngôn ngữ và đường dẫn ảnh.
• img/: Lưu ảnh PNG gốc kích thước 900 × 1200.
• thumbs/: Lưu ảnh thu nhỏ JPEG kích thước 300 × 400.
• scripts/: Chứa các script xây dựng dữ liệu, khôi phục ảnh và kiểm tra toàn vẹn.

Xây dựng lại và kiểm tra dữ liệu

Các script dữ liệu không phụ thuộc gói bên thứ ba. Sau khi chỉnh sửa dữ liệu nguồn hoặc tên tiếng Anh, bạn có thể chạy:

npm run data
npm run verify

npm run data sẽ hợp nhất các bản ghi tiếng Trung, tiếng Nhật trong scripts/source/ với bảng tên tiếng Anh, nhóm các góc nhìn theo mã tư thế, sau đó tạo data/poses.json dạng gọn.

npm run verify sẽ kiểm tra số lượng tư thế và ảnh, tên bằng ba ngôn ngữ, bản dịch series và danh mục, tham chiếu ảnh, tệp trùng lặp, định dạng và kích thước ảnh, cũng như tính đầy đủ của các khóa i18n được trang sử dụng. Sau khi chỉnh sửa dữ liệu, luôn nên chạy lệnh này để tránh ảnh bị thiếu, liên kết hỏng hoặc bản dịch chưa đầy đủ.

Thêm một nhóm tư thế mới

1. Đặt 4 đến 5 ảnh PNG gốc vào img/.
2. Đặt các ảnh thu nhỏ JPEG kích thước 300 × 400 tương ứng vào thumbs/.
3. Bổ sung mục tư thế trong bản ghi nguồn tại scripts/source/.
4. Thêm tên tiếng Anh vào scripts/en-pose-names.json.
5. Chạy npm run data && npm run verify.

Trước khi thêm ảnh, phải xác nhận bạn có quyền sử dụng và phân phối tương ứng. Mã nguồn dự án sử dụng MIT License, nhưng ảnh, dữ liệu gốc và tên không thuộc phạm vi của giấy phép MIT.

Khôi phục tệp ảnh bị thiếu

Nếu phát hiện một số ảnh bị thiếu sau khi sao chép mới hoàn toàn, bạn có thể chạy:

npm run fetch-images

Script sẽ thu thập đường dẫn ảnh từ dữ liệu tư thế, tải song song các tệp bị thiếu, bỏ qua các tệp hiện có có chữ ký hợp lệ, đồng thời kiểm tra chữ ký của tệp PNG và JPEG. Khi tải thất bại, script cũng sẽ chuyển sang nguồn khác và thử lại. Kho lưu trữ còn cung cấp workflow GitHub Actions có tên Fetch image assets.

Triển khai thành website tĩnh

Sử dụng GitHub Pages

Kho lưu trữ có sẵn .github/workflows/deploy-pages.yml. Sau khi đẩy các tệp liên quan đến website lên nhánh main, workflow sẽ tự động triển khai; cũng có thể chạy thủ công Deploy to GitHub Pages trên trang Actions.

Quy trình này chỉ đóng gói các tệp đầu vào, tài nguyên, dữ liệu và ảnh cần cho website hoạt động, không công khai toàn bộ README, script xây dựng và các tệp khác trong thư mục tài liệu.

Sử dụng Cloudflare Pages

1. Kết nối kho lưu trữ GitHub trong Cloudflare Pages.
2. Đặt Framework preset là None.
3. Để trống Build command.
4. Đặt Output directory là /.
5. Lưu cài đặt và bắt đầu triển khai.

_headers do dự án cung cấp đã cấu hình bộ nhớ đệm dài một năm cho ảnh gốc và ảnh thu nhỏ, bộ nhớ đệm năm phút cho tệp dữ liệu, đồng thời yêu cầu kiểm tra lại index.html mỗi lần.

Các nền tảng lưu trữ khác

Netlify, Vercel, dịch vụ lưu trữ đối tượng hoặc Nginx đều có thể lưu trữ dự án này. Vì không có bước xây dựng, chỉ cần dùng thư mục gốc của kho lưu trữ làm thư mục website tĩnh. Nếu sử dụng tên miền tùy chỉnh, nên sửa og:image trong index.html thành URL tuyệt đối để các nền tảng mạng xã hội dễ dàng lấy ảnh bìa.

Mẹo sử dụng nâng cao

• Giảm dung lượng triển khai: Nếu chỉ cần duyệt dạng lưới, bạn có thể chỉ giữ ảnh thu nhỏ và điều chỉnh trường ảnh gốc trong dữ liệu cùng logic tải xuống, nhưng chức năng xem ảnh lớn và tải ảnh gốc sẽ không khả dụng.
• Tận dụng tải theo nhu cầu: Lưới thư viện ảnh chỉ yêu cầu ảnh thu nhỏ JPEG; ảnh gốc PNG chỉ được tải khi mở ảnh lớn hoặc tải xuống. Không cần xóa ảnh gốc chỉ để cải thiện tốc độ hiển thị ban đầu.
• Mở rộng ngôn ngữ mới: Cần đồng thời chỉnh sửa assets/js/i18n.js, trường names của dữ liệu tư thế và bộ chuyển đổi ngôn ngữ, sau đó chạy kiểm tra tính toàn vẹn.
• Giữ đường dẫn tương đối: Tất cả tài nguyên của dự án đều sử dụng đường dẫn tương đối, vì vậy có thể triển khai tại thư mục gốc của tên miền hoặc trong thư mục con.
• Kiểm tra trước sau khi sửa: Dù thêm ảnh, điều chỉnh danh mục hay sửa bản dịch, bạn đều nên chạy npm run verify.
• Lưu ý phạm vi phát hành: Nếu sử dụng chế độ phát hành nhánh của GitHub Pages, nên giới hạn thư mục phát hành để tránh công khai tập lệnh, tài liệu hoặc các tệp không liên quan của kho lưu trữ dưới dạng tài nguyên tĩnh.

Bản quyền và phạm vi sử dụng

Mã frontend, kiểu, tập lệnh và tài liệu của dự án được cấp phép theo MIT License; bản quyền hình ảnh, dữ liệu gốc và tên gọi thuộc về các tác giả ban đầu, không nằm trong phạm vi của giấy phép MIT. Các tác giả ban đầu cho phép sử dụng tác phẩm làm tài liệu tham khảo sáng tạo, bao gồm sáng tác thương mại, biên tập và tham khảo, nhưng cấm phân phối lại, đăng lại hoặc bán lại chính dữ liệu hình ảnh. Trước khi sử dụng cho mục đích thương mại, hãy đọc hướng dẫn trên trang web gốc và tự xác nhận tính tuân thủ.

Dự án gốc là POSE-DB-01, tác giả ban đầu là ギア. RuiC-PoseAtlas là phiên bản biên soạn không chính thức, chủ yếu thực hiện việc整理 dữ liệu, bổ sung tên tiếng Anh và viết lại frontend.

Tóm tắt

RuiC-PoseAtlas sắp xếp các tư liệu tư thế đa góc phân tán thành thư viện ảnh tĩnh ba ngôn ngữ có thể tìm kiếm, lọc và tải xuống. Người dùng thông thường có thể sử dụng trực tiếp để hỗ trợ bố cục và tạo dáng, còn nhà phát triển có thể học hỏi từ kiến trúc hướng dữ liệu, ES Modules gốc, tính quốc tế hóa, khả năng truy cập và phương án triển khai tĩnh của dự án. Sau khi khởi chạy cục bộ, bạn nên làm quen trước với thao tác duyệt bằng bàn phím và liên kết sâu, rồi mở rộng dữ liệu hoặc triển khai phiên bản riêng khi cần.