BIM 협업의 오랜 골칫거리는 '파일'이다. Revit로 만든 모델을 구조 엔지니어에게 넘기려면 IFC로 내보내고, 다시 Rhino나 Grasshopper로 검토하려면 또 다른 포맷으로 변환한다. 그 과정에서 정보가 깨지고, 버전이 엉키고, 누가 최신 파일을 갖고 있는지 아무도 모른다. Speckle은 이 문제를 근본적으로 다르게 접근한다. 파일을 주고받는 대신, 모델을 잘게 쪼갠 객체(object) 단위로 데이터베이스에 올리고, Git처럼 버전을 관리하며, 어떤 툴에서든 그 데이터를 읽고 쓴다. 오픈소스이고, 자체 서버를 직접 구축할 수도 있다. 이 글에서는 Speckle의 데이터 모델을 이해하고, Python SDK인 specklepy로 실제 모델을 올리고 받아 물량을 집계하는 코드까지 살펴본다.

■ Speckle의 핵심 개념 - 파일이 아니라 객체 그래프

Speckle에서 모델은 파일이 아니라 객체들의 트리(그래프)다. 벽 하나, 문 하나가 각각 고유한 해시 ID를 가진 객체가 되고, 이들이 부모-자식 관계로 엮여 하나의 커밋(commit, 버전)을 이룬다. 동일한 객체는 해시가 같으므로 한 번만 저장되고 재사용된다(불변·중복제거). 덕분에 300MB짜리 모델에서 벽 하나만 바뀌면 바뀐 부분만 새로 올라간다. 용어를 정리하면 다음과 같다.

참고로 Speckle v3(2024~2025)로 오면서 Stream/Branch/Commit이라는 이름이 Project/Model/Version으로 바뀌었다. specklepy 3.x는 내부적으로 여전히 stream_id 인자를 쓰는 API가 남아 있어 혼용되니, 문서의 버전을 확인하는 습관이 중요하다.

■ 연결 도구(Connector) - 사람은 코드 없이도 쓴다

Speckle은 주요 저작 도구용 커넥터를 제공한다. Revit, Rhino, Grasshopper, Blender, ArchiCAD, Civil 3D, SketchUp, Power BI 등이다. 설계자는 Revit 커넥터에서 원하는 요소를 선택해 'Send' 버튼만 누르면 Speckle 서버로 올라가고, 구조 엔지니어는 Rhino 커넥터에서 'Receive'로 그 데이터를 그대로 받는다. 즉 IFC 왕복 없이 툴 사이를 오간다. 여기까지는 코드가 필요 없다. specklepy가 빛나는 지점은 이 흐름을 자동화하거나, 커넥터가 없는 곳(웹 대시보드, 견적 시스템, 사내 서버)에 데이터를 연결할 때다.

■ specklepy로 모델 올리기(send)

specklepy는 v3부터 Python 3.10 이상을 요구한다. 설치는 pip 한 줄이면 된다. 아래는 서버에 인증하고, 벽 객체 하나를 만들어 서버로 전송한 뒤 버전을 생성하는 최소 예제다.

# pip install specklepy  (v3, Python 3.10+ 필요)
from specklepy.api.client import SpeckleClient
from specklepy.api.credentials import get_default_account
from specklepy.transports.server import ServerTransport
from specklepy.api import operations
from specklepy.objects import Base

# 1) 서버 인증 - Speckle Manager에 로그인된 기본 계정 사용
client = SpeckleClient(host="app.speckle.systems")
account = get_default_account()
client.authenticate_with_account(account)

# 2) 보낼 데이터 구성 - Base 객체를 자유롭게 확장
wall = Base()
wall.speckle_type = "Objects.BuiltElements.Wall"
wall.name = "외벽-EW01"
wall.height = 3000.0        # mm
wall.thickness = 200.0
wall.fireRating = "2시간"

commit_obj = Base()
commit_obj["@walls"] = [wall]   # @ 접두사 = 분리 저장(detach)

# 3) 서버로 전송(send) 후 버전(commit) 생성
project_id = "여기에_프로젝트ID"
transport = ServerTransport(client=client, stream_id=project_id)
obj_id = operations.send(base=commit_obj, transports=[transport])

version_id = client.commit.create(
    stream_id=project_id,
    object_id=obj_id,
    message="specklepy에서 외벽 1개 전송",
)
print("업로드 완료:", version_id)

여기서 눈여겨볼 것은 @ 접두사다. 속성 이름 앞에 @를 붙이면 그 데이터는 '분리 저장(detach)'되어 별도 객체로 관리된다. 벽 목록처럼 크고 재사용 가능한 데이터를 분리해 두면 중복제거와 부분 업데이트 효율이 올라간다. transport는 데이터를 어디에 저장할지 정하는데, 서버로 보낼 땐 ServerTransport, 로컬 캐시엔 SQLiteTransport, 메모리 테스트엔 MemoryTransport를 쓴다.

■ 받아서 물량 집계까지(receive)

업로드한 데이터를 다시 받아 트리를 순회하면 견적·검토 자동화가 가능하다. 아래는 최신 버전을 받아 벽 개수와 개략 면적을 계산하는 예다.

# 4) 받기(receive) - 다른 툴/사람이 올린 최신 버전 읽기
latest = client.commit.list(project_id, limit=1)[0]
received = operations.receive(latest.referencedObject, transport)

# 5) 트리 순회하며 벽 물량 집계
total_area = 0.0
for w in received["@walls"]:
    total_area += (w.height/1000.0) * 3.0   # 예: 길이 3m 가정
print(f"수신 벽 개수: {len(received['@walls'])}, 개략 면적: {total_area:.1f} m2")

이 패턴을 확장하면 Revit에서 모델을 올릴 때마다 서버가 자동으로 물량을 재집계해 대시보드를 갱신하는 파이프라인을 만들 수 있다. 실제로 Speckle은 이런 자동화를 위한 Speckle Automate라는 서버측 함수 실행 환경도 제공하는데, 커밋이 올라올 때마다 정해진 Python 함수를 돌려 규칙 검사(예: 방화벽 내화등급 누락 체크)를 자동 수행한다.

■ 실무 활용 시나리오

첫째, QA 자동화다. 모델이 올라올 때마다 specklepy로 필수 파라미터(내화등급, 실명, 마감)가 채워졌는지 검사하고 누락을 리포트한다. 둘째, 실시간 물량·견적이다. 설계 변경이 커밋될 때마다 벽·바닥 면적을 재집계해 Power BI나 웹 대시보드에 연결한다. 셋째, 툴 간 파이프라인이다. Grasshopper에서 파라메트릭하게 생성한 형상을 Speckle로 올리고, 구조 해석 툴이 이를 받아 계산한 결과를 다시 Speckle로 되돌려 설계자가 확인하는 왕복 루프를 구성한다. 넷째, 버전 비교다. 두 커밋의 객체를 받아 어떤 요소가 추가·삭제·변경됐는지 diff를 만들어 설계 변경 이력을 추적한다.

■ 자체 서버 구축 - 데이터 주권

공용 서버(app.speckle.systems) 대신, Docker Compose로 사내에 Speckle 서버를 직접 띄울 수 있다. 발주처 보안 규정상 데이터가 외부로 나가면 안 되는 프로젝트에서 특히 유용하다. specklepy의 host 인자만 사내 서버 주소로 바꾸면 코드는 그대로 동작한다. 오픈소스(Apache 2.0 계열)라 라이선스 부담 없이 조직 규모에 맞게 확장할 수 있는 것이 Speckle의 큰 장점이다.

■ 마무리 - '파일 없는 BIM 협업'의 현실적 시작점

Speckle의 진짜 가치는 화려한 기능이 아니라, BIM 데이터를 프로그래밍 가능한 대상으로 바꿔 준다는 데 있다. 벽 하나가 해시를 가진 객체가 되는 순간, 우리는 모델을 코드로 질의하고, 검사하고, 다른 시스템에 연결할 수 있다. Dynamo나 Revit API가 '한 툴 안'의 자동화라면, Speckle은 '툴과 툴 사이, 그리고 웹까지'를 잇는 자동화다. 커넥터로 가볍게 시작해 협업 흐름을 만들고, 반복되는 검토·집계 작업이 보이기 시작하면 specklepy로 그 지점을 자동화하는 것이 가장 현실적인 도입 순서다.