PyRevit là gì? Cài đặt và tạo tool Revit

PyRevit là một trong những công cụ đáng học nhất nếu bạn muốn tự động hóa Revit bằng Python. Với PyRevit, kỹ sư, kiến trúc sư và người triển khai BIM có thể tạo nút lệnh riêng, kiểm tra mô hình, đổi tên hàng loạt, xuất dữ liệu, chuẩn hóa bản vẽ và giảm nhiều thao tác lặp lại trong quá trình làm hồ sơ. Bài viết này giúp bạn hiểu PyRevit là gì, cách cài PyRevit cho Revit, cách tạo nút tool đầu tiên, viết một script đơn giản và nhận biết các lỗi thường gặp khi bắt đầu.

PyRevit là gì?

PyRevit là một nền tảng mở rộng Revit, cho phép người dùng tạo các công cụ chạy trực tiếp trong môi trường Revit bằng Python, C# hoặc các thành phần mở rộng khác. Sau khi cài đặt, Revit sẽ có thêm tab pyRevit và người dùng có thể nạp thêm các extension riêng để tạo bộ công cụ theo nhu cầu của văn phòng.

Điểm mạnh của PyRevit không nằm ở việc thay thế Revit, mà ở việc bổ sung những lệnh nhỏ nhưng dùng rất thường xuyên. Ví dụ: đổi tên sheet theo quy tắc, kiểm tra view chưa đặt lên sheet, xuất khối lượng sang Excel, đánh số cấu kiện, tạo workset, kiểm tra lỗi mô hình hoặc tự động hóa một quy trình triển khai hồ sơ.

Sơ đồ cơ chế hoạt động từ mô hình Revit qua Revit API, script Python và PyRevit đến tool tự động hóa — Cơ chế PyRevit kết nối dữ liệu mô hình, Revit API, script Python và nút lệnh trên ribbon.

PyRevit phù hợp với ai?

PyRevit phù hợp với người dùng Revit đã bắt đầu gặp các công việc lặp lại và muốn biến kinh nghiệm thao tác thành công cụ. Không nhất thiết phải là lập trình viên chuyên nghiệp, nhưng người học cần hiểu cơ bản về Revit, family, view, sheet, parameter và cách mô hình Revit lưu dữ liệu.

Kỹ sư kết cấu: dùng PyRevit để kiểm tra mô hình, xử lý dầm/cột/sàn, xuất dữ liệu và hỗ trợ triển khai hồ sơ.
Kiến trúc sư: dùng PyRevit để quản lý phòng, view, sheet, vật liệu, thống kê và kiểm tra mô hình.
BIM coordinator: dùng PyRevit để chuẩn hóa quy trình, kiểm tra dữ liệu và giảm lỗi khi nhiều người cùng làm việc.
Người học Revit API: dùng PyRevit như môi trường thực hành nhanh trước khi chuyển sang add-in C# phức tạp hơn.

Cách cài PyRevit cho Revit

Cách an toàn nhất là tải bộ cài từ trang phát hành chính thức của pyRevit, sau đó kiểm tra phiên bản Revit bạn đang dùng có được hỗ trợ tốt hay chưa. Với các bản Revit mới, bạn nên đọc ghi chú phát hành trước khi cài vì khả năng tương thích có thể thay đổi theo từng phiên bản pyRevit.

Đóng toàn bộ phiên bản Revit đang mở.
Truy cập trang phát hành chính thức của pyRevit trên GitHub và tải installer phù hợp.
Chạy file cài đặt, chọn thư mục cài đặt theo mặc định hoặc theo quy định của công ty.
Mở Revit. Nếu Revit hỏi có cho phép nạp add-in hay không, chọn Always Load nếu bạn tin cậy nguồn cài đặt.
Kiểm tra trên ribbon có tab pyRevit hay chưa.
Nếu tab chưa xuất hiện, thử khởi động lại Revit, kiểm tra Add-ins, hoặc kiểm tra lại đúng phiên bản pyRevit/Revit.

Trong môi trường công ty, nên thống nhất một phiên bản pyRevit, một thư mục extension chung và quy định ai được cập nhật tool. Việc này giúp tránh tình trạng mỗi máy một bản, tool chạy khác nhau hoặc khó kiểm soát lỗi khi triển khai dự án thật.

Cách tạo nút tool PyRevit đầu tiên

PyRevit tổ chức tool theo dạng bundle. Hiểu đơn giản, mỗi thư mục có hậu tố đặc biệt sẽ tương ứng với một thành phần trên ribbon. Một extension thường có cấu trúc như sau:

DLhouse.extension
└── DLhouse.tab
    └── Hoc PyRevit.panel
        └── Hello Revit.pushbutton
            ├── script.py
            └── icon.png

Trong đó:

.extension là gói extension để pyRevit nhận diện.
.tab là tab hiển thị trên ribbon Revit.
.panel là nhóm lệnh trong tab.
.pushbutton là một nút lệnh.
script.py là file Python sẽ chạy khi người dùng bấm nút.
icon.png là icon của nút, không bắt buộc nhưng nên có để giao diện dễ nhận biết.

Bạn có thể đặt extension trong thư mục extension của pyRevit hoặc khai báo một thư mục riêng bằng công cụ quản lý extension. Khi chỉnh sửa xong, dùng lệnh reload/refresh của pyRevit hoặc khởi động lại Revit để ribbon cập nhật.

Viết script PyRevit đầu tiên

Với script đầu tiên, không nên bắt đầu bằng một lệnh sửa mô hình. Hãy bắt đầu bằng lệnh đọc thông tin dự án và hiện thông báo. Cách này giúp kiểm tra môi trường PyRevit, Revit API và cấu trúc bundle trước khi đi vào các thao tác có transaction.

# -*- coding: utf-8 -*-
from Autodesk.Revit.UI import TaskDialog
from pyrevit import revit

doc = revit.doc

if doc:
    message = "Đang mở dự án: {}".format(doc.Title)
else:
    message = "Chưa có file Revit đang mở."

TaskDialog.Show("DLhouse PyRevit", message)

Lưu file trên với tên script.py trong thư mục Hello Revit.pushbutton. Sau đó reload pyRevit và bấm nút mới trên ribbon. Nếu hộp thoại hiện tên dự án, nghĩa là extension, panel, pushbutton và script đã được nạp đúng.

Khi nào cần dùng transaction?

Trong Revit API, các thao tác chỉ đọc dữ liệu thường không cần transaction. Nhưng nếu script thay đổi mô hình, ví dụ đổi tên view, sửa parameter, tạo sheet, tạo element hoặc di chuyển đối tượng, bạn cần đặt thao tác đó trong transaction. Đây là điểm người mới học PyRevit rất dễ bỏ qua.

from pyrevit import revit

doc = revit.doc

with revit.Transaction("DLhouse - Ten thao tac"):
    # Dat cac lenh sua model o day
    pass

Nguyên tắc của DLhouse khi viết tool là tách rõ ba phần: chọn dữ liệu, kiểm tra điều kiện, sau đó mới sửa mô hình trong transaction. Cách này giúp tool dễ kiểm soát lỗi và hạn chế thay đổi nhầm dữ liệu dự án.

Lỗi thường gặp khi dùng PyRevit

Khi mới bắt đầu, phần lớn lỗi không nằm ở Revit API phức tạp mà nằm ở cấu trúc thư mục, phiên bản cài đặt hoặc cách viết script. Dưới đây là các lỗi nên kiểm tra trước.

Không thấy tab hoặc nút tool trên ribbon

Kiểm tra tên thư mục có đúng hậu tố .extension, .tab, .panel, .pushbutton không. Chỉ sai một ký tự, pyRevit có thể không nhận diện được. Sau khi sửa, cần reload pyRevit hoặc khởi động lại Revit.

Bấm nút nhưng script không chạy

Kiểm tra file có đúng tên script.py hay chưa. Với command bundle, pyRevit sẽ tìm file script phù hợp trong thư mục nút lệnh. Nếu file đặt sai tên, sai vị trí hoặc bị lưu dưới dạng script.py.txt, nút có thể không chạy.

Lỗi tiếng Việt hoặc ký tự đặc biệt

Nên lưu file Python bằng UTF-8 và thêm dòng # -*- coding: utf-8 -*- ở đầu file nếu script có tiếng Việt. Với đường dẫn thư mục, hạn chế dùng ký tự quá đặc biệt để tránh lỗi khi chia sẻ extension cho nhiều máy.

Lỗi do thiếu transaction

Nếu script sửa dữ liệu Revit nhưng không có transaction, Revit API thường sẽ báo lỗi. Hãy phân biệt rõ script chỉ đọc dữ liệu và script thay đổi mô hình.

Lỗi do phiên bản Revit hoặc pyRevit không tương thích

Với Revit phiên bản mới, cần kiểm tra ghi chú release của pyRevit. Không nên cài nhiều bản pyRevit chồng chéo nếu chưa hiểu rõ cách quản lý phiên bản, vì có thể gây xung đột loader hoặc add-in.

Quy trình học PyRevit nên đi theo

Nếu học PyRevit để áp dụng vào công việc thật, nên đi từ tool nhỏ đến tool có quy trình. Đừng bắt đầu bằng một add-in lớn. Một lộ trình thực tế có thể như sau:

Sơ đồ lộ trình học PyRevit từ Python cơ bản, Revit API, extension, transaction đến tool dùng trong dự án — Lộ trình học PyRevit nên đi từ Python và Revit API cơ bản đến tool chỉ đọc, transaction và công cụ dùng trong dự án.

Hiểu Revit API ở mức element, category, parameter, view, sheet.
Cài PyRevit và tạo được extension đầu tiên.
Viết script đọc dữ liệu: đếm view, sheet, family, category.
Viết script lọc và xuất dữ liệu sang Excel/CSV.
Viết script sửa dữ liệu có transaction, bắt đầu từ thao tác ít rủi ro.
Đóng gói tool theo tab/panel, thêm icon, ghi hướng dẫn sử dụng.
Kiểm thử trên file mẫu trước khi dùng cho dự án thật.

Với DLhouse, PyRevit không chỉ là bài học lập trình. Đây là cách biến kinh nghiệm triển khai hồ sơ thành công cụ: tool nào giảm lỗi, giảm thời gian và dễ kiểm tra lại thì mới đáng đưa vào quy trình làm việc.

Tài liệu tham khảo

Liên hệ học PyRevit và Revit API

Nếu bạn muốn học PyRevit theo hướng ứng dụng thực tế trong hồ sơ kiến trúc, kết cấu và bóc khối lượng, DLhouse có thể hỗ trợ theo lộ trình từ Revit API cơ bản đến xây tool nội bộ cho quy trình làm việc. Bạn có thể gửi yêu cầu tư vấn hoặc liên hệ hotline 0395.316.829 để trao đổi rõ hơn.

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

Phần mềm, Python / Lập trình

PyRevit là gì? Hướng dẫn cài đặt và tạo tool đầu tiên