Đưa bộ tool PyRevit có sẵn vào Revit

Đưa bộ tool PyRevit có sẵn vào Revit là tình huống rất thường gặp khi bạn nhận một bộ tool từ đồng nghiệp, từ phòng BIM hoặc từ đơn vị phát triển nội bộ. Lúc này bạn không cần viết tool từ đầu; việc quan trọng là kiểm tra đúng cấu trúc thư mục, đặt bộ tool ở vị trí ổn định, thêm đường dẫn extension vào pyRevit và reload để tab/panel hiện trong Revit.

Bài này nối tiếp bài cài PyRevit cho Revit. Nếu bạn chưa cài pyRevit hoặc chưa thấy tab pyRevit trong Revit, hãy xử lý bước cài đặt trước. Nếu đã có pyRevit và đang có sẵn một folder tool, bài này sẽ giúp bạn đưa bộ tool đó vào Revit theo quy trình an toàn, tránh lỗi sai thư mục hoặc mất tool khi cập nhật pyRevit.

Khi nào nên dùng bộ tool PyRevit có sẵn?

Dùng bộ tool có sẵn phù hợp khi bạn đã có một extension ổn định, đã được người khác viết và muốn triển khai nhanh cho cá nhân hoặc nhóm. Đây là cách làm thực tế hơn nhiều so với việc mỗi người tự viết lại tool từ đầu.

Bạn nhận một folder như DLhouseTools.extension từ người phát triển tool.
Công ty có bộ tool dùng chung cho triển khai hồ sơ, kiểm tra model hoặc bóc khối lượng.
Bạn muốn test nhanh một extension trước khi đưa vào quy trình làm việc chính thức.
Nhóm thiết kế muốn dùng chung một bộ tool qua thư mục mạng nội bộ hoặc thư mục đồng bộ.

Với người mới, nên ưu tiên hiểu cách nạp bộ tool có sẵn trước. Khi đã biết pyRevit đọc extension thế nào, việc tự tạo tab hoặc viết nút tool riêng sẽ dễ kiểm soát hơn.

Extension PyRevit là gì?

Theo tài liệu pyRevit, extension là một nhóm tool được tổ chức thành các bundle để pyRevit tạo giao diện trong Revit. Folder extension thường kết thúc bằng .extension. Bên trong extension có thể có tab, panel, pushbutton và các file như script.py, icon.png, lib.

Ví dụ dễ hiểu:

D:DLhouseTools
└── DLhouseTools.extension
    └── DLhouse.tab
        └── Ket Cau.panel
            └── Tinh Khoi Luong.pushbutton
                ├── script.py
                └── icon.png

Điểm cần nhớ là pyRevit không chỉ đọc file script.py rời rạc. Nó đọc cả cấu trúc bundle. Vì vậy chỉ cần sai tên folder hoặc đặt sai cấp thư mục, tool có thể không hiện trên ribbon.

Quy trình đưa bộ tool PyRevit vào Revit

Sơ đồ quy trình nhận bộ tool PyRevit, thêm đường dẫn extension, reload và kiểm tra tool trong Revit — Quy trình đưa bộ tool PyRevit có sẵn vào Revit: nhận folder, kiểm tra cấu trúc, thêm đường dẫn, reload và test tool.

Quy trình tổng quát gồm sáu bước:

Nhận bộ tool và giải nén nếu đang là file .zip.
Kiểm tra có folder kết thúc bằng .extension.
Đặt bộ tool vào thư mục ổn định, ví dụ D:DLhouseTools hoặc thư mục chung của công ty.
Mở Revit, vào pyRevit Settings hoặc công cụ Extensions để thêm đường dẫn thư mục cha chứa extension.
Reload pyRevit hoặc khởi động lại Revit.
Kiểm tra tab/panel/tool đã hiện và bấm thử một tool đơn giản.

Tài liệu chính thức của pyRevit cũng hướng dẫn cách thêm extension thủ công bằng cách thêm đường dẫn thư mục chứa extension vào pyRevit Settings. Điều cần chú ý là đường dẫn cần trỏ đến thư mục cha đang chứa folder .extension, không phải lúc nào cũng trỏ thẳng vào folder .extension.

Kiểm tra cấu trúc thư mục trước khi nạp tool

Sơ đồ cấu trúc thư mục .extension .tab .panel .pushbutton và script.py trong bộ tool PyRevit — Cấu trúc tối thiểu cần kiểm tra trước khi nạp một bộ tool PyRevit vào Revit.

Trước khi thêm đường dẫn vào pyRevit, bạn nên kiểm tra nhanh cấu trúc. Một bộ tool cơ bản nên có các cấp sau:

.extension: folder ngoài cùng của bộ tool.
.tab: tab sẽ hiện trên ribbon Revit.
.panel: nhóm tool bên trong tab.
.pushbutton: một nút bấm cụ thể.
script.py: file Python chạy khi bấm nút.
icon.png: icon của nút, nên có nhưng không phải lúc nào cũng bắt buộc.

Nếu bộ tool nhận từ người khác không có cấu trúc này, bạn nên hỏi lại người gửi trước khi tự sửa. Việc đổi tên folder tùy tiện có thể làm mất liên kết tới thư viện, icon hoặc cấu hình bên trong tool.

Cách thêm extension bằng pyRevit Settings

Đây là cách dễ nhất cho người dùng phổ thông:

Mở Revit.
Vào tab pyRevit.
Mở Settings hoặc mục quản lý extension tùy phiên bản pyRevit.
Tìm phần Custom Extension Folders.
Thêm đường dẫn thư mục cha, ví dụ D:DLhouseTools.
Lưu lại, reload pyRevit hoặc khởi động lại Revit.

Nếu folder của bạn là D:DLhouseToolsDLhouseTools.extension, đường dẫn nên thêm thường là D:DLhouseTools. Sau khi reload, pyRevit sẽ tìm extension bên trong thư mục đó và dựng lại giao diện ribbon.

Cách kiểm tra extension đã nạp đúng chưa

Sau khi reload, hãy kiểm tra theo thứ tự:

Tab mới có xuất hiện trên ribbon Revit không?
Panel bên trong tab có đúng tên không?
Các nút bấm có hiện icon/tên tool không?
Bấm một tool đơn giản có báo lỗi không?
Nếu tool xử lý model, hãy test trên file mẫu trước khi dùng trong dự án thật.

Nếu cần xem môi trường pyRevit đang nhận gì, có thể dùng lệnh:

pyrevit env

Lệnh này không sửa gì trong Revit, chỉ giúp kiểm tra môi trường pyRevit, các bản Revit và thông tin cấu hình. Khi cần hỗ trợ kỹ thuật, bạn nên chụp hoặc copy kết quả này để người viết tool dễ kiểm tra hơn.

Lỗi thường gặp khi đưa bộ tool PyRevit vào Revit

Thêm đúng folder nhưng tab không hiện

Thường do bạn thêm nhầm cấp thư mục. Nếu extension nằm trong D:DLhouseToolsDLhouseTools.extension, hãy thêm thư mục cha D:DLhouseTools, sau đó reload lại pyRevit.

Folder có extension nhưng nút không hiện

Kiểm tra các cấp .tab, .panel, .pushbutton. Một nút pushbutton cần có script chạy được, thường là script.py.

Tool hiện nhưng bấm vào báo lỗi

Lúc này pyRevit đã nạp giao diện, nhưng script bên trong lỗi. Nguyên nhân có thể là thiếu thư viện, thiếu file cấu hình, sai phiên bản Revit hoặc tool cần chạy trong điều kiện cụ thể như phải chọn đối tượng trước.

File tải từ Internet bị Windows chặn

Nếu bạn nhận bộ tool dạng zip tải từ Internet, Windows có thể chặn một số file. Có thể chuột phải vào file zip, chọn Properties và Unblock trước khi giải nén. Với thư mục đã giải nén, người dùng có kinh nghiệm có thể dùng PowerShell:

Get-ChildItem "D:DLhouseTools" -Recurse | Unblock-File

Chỉ thực hiện khi bạn tin tưởng nguồn bộ tool. Không nên chạy tool pyRevit không rõ nguồn trong file dự án thật.

Nên đặt bộ tool ở đâu để dùng ổn định?

Không nên để extension trong thư mục tải về tạm như Downloads hoặc Desktop nếu dùng lâu dài. Một vài vị trí ổn định hơn:

D:DLhouseTools cho máy cá nhân.
Thư mục mạng nội bộ cho công ty, nếu đường dẫn ổn định và user có quyền đọc.
Thư mục đồng bộ nội bộ, nhưng cần tránh trường hợp tool bị cập nhật giữa lúc đang làm dự án.

Với nhóm nhiều người, nên quy định một thư mục chung và một phiên bản tool đang dùng. Không nên mỗi máy tự copy một bản khác nhau, vì rất khó kiểm tra lỗi khi mỗi người chạy một phiên bản.

Khi nào cần nhờ người viết tool kiểm tra?

Nếu tab đã hiện nhưng tool chạy sai kết quả, báo lỗi API hoặc chỉ lỗi trên một phiên bản Revit cụ thể, bạn nên gửi lại các thông tin sau cho người viết tool:

Phiên bản Revit đang dùng.
Phiên bản pyRevit hoặc ảnh chụp pyrevit env.
Đường dẫn folder extension.
Ảnh chụp lỗi khi bấm tool.
File mẫu nếu lỗi phụ thuộc model.

Cách này giúp người hỗ trợ phân biệt được lỗi nạp extension, lỗi cấu trúc thư mục hay lỗi logic trong script.

Tài liệu tham khảo

Liên hệ hỗ trợ triển khai tool PyRevit

Nếu bạn có bộ tool PyRevit nhưng chưa biết cách đưa vào Revit, hoặc muốn chuẩn hóa cách triển khai tool cho nhóm thiết kế/kết cấu, DLhouse có thể hỗ trợ kiểm tra cấu trúc extension, hướng dẫn cài đặt và đào tạo quy trình sử dụng tool.

Liên hệ DLhouse để được hỗ trợ triển khai tool PyRevit.

Cần trao đổi thêm?

DLhouse có thể hỗ trợ bạn kiểm tra hồ sơ, thiết kế hoặc triển khai Revit thực tế.

Gửi thông tin công trình hoặc nội dung bạn đang cần xử lý, DLhouse sẽ phản hồi theo đúng nhu cầu: tư vấn thiết kế, hồ sơ kỹ thuật, kết cấu hoặc phần mềm Revit.

Gửi thông tin tư vấn -> Gọi 0914.977.990

Python / Lập trình, Tài liệu khóa học

Cách đưa bộ tool PyRevit có sẵn vào Revit