Balcony Shaper

功能概述

Balcony Shaper 是一個在 Revit 內部開啟的工具視窗（視窗標題為「Balcony Shaper」，附著在 Revit 主視窗旁、自動連結當前開啟的檔案）。它用三種排列演算法——沿樞軸線的「單側排列」、在填充區域內的「範圍隨機」、沿側邊曲線的「曲線配置」——把陽台的地板、欄牆與扶手一次批量算出來並建進模型，省去逐層手動繪製的龐大工作量。

簡單說：你給它一條樞軸線（或側邊曲線）加上填充區域範圍，再勾選要做的樓層，它就算好每個陽台的位置、尺寸並預覽給你確認，滿意後一鍵建立。它特別適合住宅大樓標準陽台、需要立面變化的高樓、以及弧形外牆的陽台配置。

30 秒快速開始

在 Revit 中開啟專案檔案，切換到能看到「詳細線（Detail Line）」與「填充區域」的平面視圖。
依模式挑好基準：「M1,M3」群組按 Pick 挑樞軸線、「M2,M3」群組挑好填充區域，並在左側樓層清單勾選要做的樓層。

工具視窗長什麼樣？（3 個分頁導覽）

工具視窗中央是三個模式分頁；每個分頁只放一個 Random 預覽按鈕與一個「Preview」預覽區，所有參數都在左、中、右三欄的群組框裡（左欄：樓層清單、「Balcony Limit」、「M3 HouseHold」；中欄：「M1」、「M1,M3」、「M2,M3」、「M3」；右欄：「Generator」）。先記住這張表：

分頁	用途（一句話）	代表性功能
Mode 1:Single Side Pattern	沿樞軸線單側排列陽台，適合平面重複的標準住宅	Random 預覽（立面圖）、Max. Pattern、樞軸線 Pick、Create
Mode 2:Range Random	在填充區域內隨機切割生成，適合要立面變化的高樓	三種 Hatch 挑選、Seg. Factor、Random Level 清單、Create
Mode 3:Along With Curve	側邊曲線處生成固定深度陽台、其餘隨機，適合弧形外牆	SideCurve Pick、Fixed Balcony Depth、M3 HouseHold、Create

💡 找不到功能怎麼辦？

先翻上面的分頁導覽表，或到本頁最下方「快速查詢：遇到什麼狀況用什麼功能」對號入座。
「操作步驟」章節先依 3 個模式分頁、再依共用控制區排列；每個功能都標有 📍（所在群組框與按鈕的原始英文），看到相同文字就是找對了位置。
介面中反覆出現的按鈕：「Pick」（到圖面挑元素）、「Random」（重算預覽）、「Create」（確認生成）、「From Watson」（從 BIM-Watson 取數）、「DeleteAll」（刪除本工具所建元素）。

三種模式速覽

Mode 1:Single Side Pattern（單側排列）

以一條直線「樞軸線」為基準：每個勾選的樓層從樞軸線中點（或側邊曲線點）沿線方向、偏移一個隨機間距放置陽台段，深度沿線的法線方向延伸（可反向）。陽台長度取「面積上限 ÷ 深度」與剩餘半長度的較小者。只生成地板。

Mode 2:Range Random（範圍隨機）

以填充區域為界：對每個樓層在「陽台 / 景觀陽台」填充區內投隨機切割線，把區域切成若干塊，直到剩餘總面積小於等於該樓層的面積上限。可控制切割段數、垂直切割修正與屋戶（房間）邊界對齊。

Mode 3:Along With Curve（沿曲線配置）

在「側邊曲線」與各樓層的交會點先生成一個固定深度的標準陽台（含「Split Depth Extend」過渡區），再把扣除固定陽台後的剩餘範圍用 Mode 2 式隨機切割配置景觀陽台與標準陽台。

主要功能模組

✓ 十大類用途

三種佈局演算法：單側排列（M1）、範圍隨機（M2）、沿曲線配置（M3），各佔一個分頁
先預覽後生成：每個分頁的 Random 按鈕在「Preview」區畫出預計配置（M1 為立面示意、M2/M3 為平面輪廓），可反覆重抽直到滿意
元素生成：陽台地板（樓板類型）、外緣欄牆（牆體類型＋高度）、扶手（以牆體模擬、可設高度與內縮偏移）、結構標記（Struct.）
面積與深度控制：「Balcony Limit」群組的標準／景觀陽台面積上限（m²）與深度（mm），可分樓層覆寫
法規整合：「Use Watson Limit」＋「From Watson」直接採用 BIM-Watson 計算的各樓層陽台面積上限（標準 15%、景觀 12.5% 扣除既有面積）
屋戶對齊：「M3 HouseHold」＋「From Watson」載入 BIM-Watson 的屋戶/房間資料，勾「Map HouseHold」讓隨機切割沿房間邊界下刀
分樓層自訂：樓層清單可逐層勾選、逐層指定專屬樞軸線（列內「Pick」按鈕）、逐層顯示 Watson 面積上限
隨機性控制：Max. Pattern、Gap Factor（最小～最大）、Smooth Gap、Seg. Factor、Force Seg.、Perpendicular Cut、Random Balcony Type 等參數控制間距與分段節奏
設定檔管理：「Setting」選單的 Open / Load / Save / SaveAs，設定檔為 .bss 檔案，可團隊共享
安全機制：預覽制、執行前「Confirm?」確認、每次 Create 為單一交易（可整批復原）、DeleteAll 只刪本工具記錄在案的已建元素

使用情境

以下情境都附上實際要用的分頁、群組與按鈕，可以直接照著做：

情境一：住宅大樓標準陽台（模式一）

每層平面重複的住商大樓：在「Mode 1:Single Side Pattern」分頁，先在「M1,M3」群組按 Pick 挑外牆的直線詳細線作樞軸線，左側樓層清單勾選所有住戶樓層，「Balcony Limit」群組確認面積與深度上限，按 Random 預覽立面配置；方向若朝室內就勾「M1,M3」群組的「Normal Reverse」。滿意後到「Generator」群組的「Mode 1」按 Create（「Confirm?」答「Yes」）一次生成全部楼层的陽台地板。生成前務必備份檔案（詳見前置設定）。

情境二：每層樞軸線不同的建築（模式一＋分層樞軸線）

建築各層外牆位置不同時：勾選「Generator」群組「Mode 1」子群組的「Use Separate Pivot Curve」，在樓層清單中選取要個別指定的樓層（可多選），點該列最右側的 Pick 按鈕挑該層專屬的直線詳細線（「M1,P3:Piv. Curve」欄會填入元素 ID）。要取消某些樓層的專屬線，選取後按「Balcony Limit」群組的 M1,M3:Clear Cus. Pivot。

情境三：旅館／商業大樓的立面變化（模式二）

要避免陽台一排排重複：在「Mode 2:Range Random」分頁，於「M2,M3」群組挑好「Base Hatch」（整體範圍）、「Balcony Hatch」（標準陽台範圍）、「Scenic Balcony Hatch」（景觀陽台範圍）三個填充區域，用「Seg. Factor」控制切割段數（1～5，預設 2）、「Perpendicular Cut」修正平行於邊界的切割線；勾選樓層與「Random Level」後按 Random，平面預覽會一層層鋪出（每行 5 層）。反覆重抽到滿意再 Create。

情境四：弧形外牆的陽台（模式三）

弧形或斜向外牆：在「Mode 3:Along With Curve」分頁，「M3」群組按 Pick 挑一條「模型線（Model Line）」作 SideCurve（它決定每層固定陽台的落點），設定「Fixed Balcony Depth」（預設 1100 mm）與「Split Depth Extend」（預設 600 mm，固定陽台與景觀區之間的過渡延伸）。預覽時每層會在側邊曲線處先放一個固定陽台，其餘範圍隨機。同樣需要挑好三個填充區域並勾選樓層。

情境五：陽台面積要跟法規檢討連動

陽台面積受法規限制（標準陽台以樓地板面積 15% 為上限、景觀陽台 12.5%，並扣除既有陽台/大廳面積）：在「Balcony Limit」群組勾「Use Watson Limit」、選「Building」編號（1～20）後按 From Watson，工具會向執行中的 BIM-Watson 程序取回各樓層上限並填入樓層清單的「B. Limit」「S. Limit」欄（成功後紅色小圓點變綠）。之後預覽與生成就會用這些分樓層上限取代手動輸入的 m² 值。

情境六：一次做出地板＋欄牆＋扶手（模式二/三）

在「Generator」群組勾「Floor」（選樓板類型）、「Wall」（選牆體類型、設「Height」，預設 1200 mm）、「Balcony Handrails」「Scenic Handrails」（選扶手牆體類型、設「Handrail Height」與 cm 偏移）。欄牆與扶手都以「Base Hatch」為外緣判定基準——沒挑 Base Hatch 就不會產生欄牆與扶手（保護邏輯：貼著建築側的牆段會被自動略過）。

情境七：切割要跟著屋戶（房間）走

讓隨機切割盡量落在戶與戶之間：先在「M3 HouseHold」群組選「Building」編號、按 From Watson 載入屋戶/房間對應（成功後圓點變綠；模型中需要有對應的房間且面積大於 0），再勾「M2,M3」群組的「Map HouseHold」。之後 M2/M3 的隨機切割會優先從相鄰房間的交界下刀。

情境八：生成錯了要重來

每次 Create 是單一交易：回 Revit 按一次 Ctrl+Z 即可整批復原。若要直接刪掉本工具建出的元素，按「Generator」群組的 DeleteAll（「Confirm?」答「Yes」）——它只刪「本次工作階段建立、或已載入設定檔中記錄在案」的元素，不會誤刪你自己建的東西。重新安排時再按該分頁的 Random 重抽預覽即可。

前置設定

第一步：開啟並連結

在 Revit 中開啟目標檔案，切換到能看到目標「詳細線」與「填充區域」的平面視圖。
執行 Balcony Shaper 指令。工具視窗附著在 Revit 主視窗旁並自動連結當前檔案，不需要手動匯入；若出現 Wylin 登入視窗，先完成登入。
重複執行指令時焦點會回到已開啟的視窗（單一執行個體），不會疊加第二個視窗。關閉 Revit 檔案時工具視窗也會自動關閉。

第二步：選擇處理範圍

樓層清單（左欄上方）：列出所有高程大於 0 的樓層（地下一層、0.00 等不列出）。勾選要生成陽台的樓層。
Random Level 清單（「M2,M3」群組）：模式二、三的「第二道開關」——一個樓層必須同時在樓層清單與 Random Level 清單都被勾選，才會參與隨機分割（預設 Random Level 全勾）。
階段（「Generator」群組上方的「Phase」清單）：單選、預設第一個階段；必須有選階段才能生成（否則回報 "No Phase Selected."）。
挑取基準元素：「Pick」按鈕會讓你切到 Revit 圖面點選——樞軸線與分層樞軸線只能挑直線詳細線（Detail Line）（弧線會報 "Arc is not supported."）；側邊曲線只能挑模型線（Model Line）；三種 Hatch 只能挑填充區域（Filled Region）。取消挑選按 Esc。

💡 連結與挑取狀態確認

挑不到元素或生成無反應時請確認：目標詳細線/模型線/填充區域在當前視圖看得見、填充區域是封閉畫好的、樞軸線是直線不是弧線、檔案可編輯。另外注意：挑填充區域時畫面提示文字仍寫「Pick a DetailLine」，這是介面的文字問題，實際要挑的是填充區域。

第三步：執行並觀察結果

先按該模式分頁的 Random 預覽（純計算，不改模型），在「Preview」區檢查配置；不滿意就再按一次 Random 重抽（每次結果都不同）。
確認勾選的生成選項（「Generator」群組的 Floor / Wall / 扶手等）與面積、深度參數沒設錯。
按該模式的 Create，在「Confirm?」對話框答「Yes」開始生成。

⚠️ 執行前一定先備份

本工具會在模型中大量建立樓板、牆體元素，DeleteAll 會刪除記錄在案的已建元素。每次 Create 是單一交易（可整批 Ctrl+Z），但一旦你開始手動編輯、存檔或關檔，復原就失效了。正式批量生成前請先「另存新檔」。

操作步驟

本章先依三個模式分頁（每頁的完整作業流程）排列，再說明三個分頁共用的控制區（樓層清單、「Balcony Limit」、「Generator」、「Setting」選單）。每個功能都標明位置（📍 所在群組框與按鈕，介面原文）、一句話說明與操作步驟。介面中反覆出現的按鈕：「Pick」（到圖面挑元素）、「Random」（重算預覽）、「Create」（確認後生成）、「From Watson」（向 BIM-Watson 取數）。

分頁 1：Mode 1:Single Side Pattern

單側排列模式：沿一條直線樞軸線為每層放置陽台段，本模式只生成陽台地板（「Generator」的 Wall/扶手選項對 M1 不生效）。

1.1 隨機預覽（Random）

📍 分頁「Mode 1:Single Side Pattern」最上方的 Random 按鈕；結果畫在「Preview」群組

一句話：依目前參數為所有勾選樓層重算一次陽台配置並畫出立面示意圖（灰線為各樓層、長方形為陽台段，高度以「Height」值表示），純粹預覽、不改模型。

確認已挑樞軸線（「M1,M3」群組）、勾選目標樓層、面積上限大於 0。
按 Random，「Preview」區顯示立面配置；圖例在預覽區下方：綠色「=Scenic Balcony」、粉紅「=Basic Balcony」。
不滿意就再按一次 Random 重抽（每次隨機結果都不同）。

⚠️ 預覽的前提

沒挑樞軸線會報 "No Pivot DetailCurve"；樞軸線是弧線會報 "Arc is not supported."（只接受直線詳細線）。某樓層面積上限為 0 時該層會被跳過，日誌顯示 "Level:樓層名 Has no available Area. Skip"——預覽少了一層是這個原因，不是錯誤。

1.2 模式一參數（M1 群組）

📍 中欄「M1」群組：Max. Pattern（1～50，預設 3）、勾選「Random Balcony Type」（預設勾選）、「Balcony Type Reverse」（預設勾選）、「Use SideCurve」（預設勾選）

一句話：控制 M1 每個樓層陽台段的「間距候選數量、兩側類型怎麼配、起點在哪」。

Max. Pattern：隨機間距的候選寬度數量（每層會從中抽一個作為陽台段起點的偏移）。數值越大，候選間距越多樣。
勾「Random Balcony Type」：樞軸線中點兩側的標準/景觀類型隨機決定並交替；不勾則起始側固定為標準陽台、對側固定為景觀陽台。
「Balcony Type Reverse」（預設勾選）：翻轉起始方向（換到哪一側先排）。
勾「Use SideCurve」：每層陽台段的起點改取「SideCurve」（M3 群組挑選的模型線）投影到該層高程的點；未挑 SideCurve 時日誌提示 "SideCurve is not available."，投影失敗會報 "SideCurve Projection Failed."。

1.3 樞軸線、法線與間距（M1,M3 群組）

📍 中欄「M1,M3」群組：「Pivot Line」旁的 Pick 按鈕、「Normal」顯示值、「Normal Reverse」勾選、「Gap Factor」最小值～最大值（mm）、「Smooth Gap」勾選＋「Smooth Factor」（1～20，預設 1）

一句話：定義陽台往哪一排（樞軸線＋法線方向）與每層陽台段離中點多遠（間距範圍＋平滑節奏）。

按「Pivot Line」旁的 Pick，在 Revit 中挑一條直線詳細線（提示 "Pick a DetailLine"；元素 ID 會填入旁邊輸入框）。
看「Normal」顯示的法線整數值（如 "1,0"）：陽台深度朝該方向延伸；生成到室內側就勾「Normal Reverse」翻轉。
設「Gap Factor」最小值～最大值（mm，預設 500～2000）：M1 的間距候選、M3 的固定陽台半寬都從這個範圍抽。
勾「Smooth Gap」：間距不再是純隨機，而是依「Smooth Factor」（步進倍率，值越大單步變化越大、節奏感越強）在最小～最大之間來回走勢。

1.4 生成（Generator 群組 Mode 1 子群組）

📍 右欄「Generator」群組內「Mode 1」子群組：勾選「Use Separate Pivot Curve」＋按 Create

一句話：把最近一次 Random 預覽的配置建進模型——只建陽台地板（每層每段一塊，樓板類型取自「Generator」的 Floor 下拉選單）。

勾「Use Separate Pivot Curve」：該樓層若已在樓層清單指定專屬樞軸線（列內 Pick）就用專屬線，沒指定的層回退用主樞軸線。
按 Create，在「Confirm?」對話框答「Yes」。
一次 Create 是單一交易：完成後在 Revit 按一次 Ctrl+Z 可整批復原。日誌逐筆出現 "Floor Created:ID"。

💡 M1 不建牆與扶手

「Generator」群組的「Wall」「Balcony Handrails」「Scenic Handrails」只對模式二、三生效。M1 若需要欄牆/扶手，請改用 M2 或 M3（可用填充區域把 M1 的結果包起來再做），或在 M1 建完地板後手動補牆。

分頁 2：Mode 2:Range Random

範圍隨機模式：在填充區域內用隨機切割線把範圍切成塊，生成地板（可含欄牆、扶手）。

2.1 隨機預覽（Random）

📍 分頁「Mode 2:Range Random」最上方的 Random 按鈕；結果畫在「Preview」群組

一句話：為「樓層清單 ∩ Random Level 清單」都勾選的樓層各重算一次隨機分割，平面輪廓預覽（每行 5 層往右再往下鋪；粉紅線＝標準陽台、綠線＝景觀陽台）。

確認已挑「Base Hatch」「Balcony Hatch」「Scenic Balcony Hatch」（見 2.2）、面積上限已設定、樓層雙勾完成。
按 Random，「Preview」區逐層顯示輪廓；日誌逐層出現 "Random Level:ID"。
不滿意再按一次 Random 重抽；某層抽不到合格分割時日誌回報 "Maximum Trying Reached."（見疑難排解）。

2.2 填充區域定義與切割參數（M2,M3 群組）

📍 中欄「M2,M3」群組：「Random Level」清單（勾選框）、三列 Hatch 各附 Pick 按鈕與 ID 框（「Base Hatch」「Balcony Hatch」「Scenic Balcony Hatch」）、「Seg. Factor」（1～5，預設 2）、「Force Seg.」勾選、「Map HouseHold」勾選、「Perpendicular Cut」勾選、「Ditribute Scenic Balcony」勾選（介面原始拼法）

一句話：決定 M2/M3 「在哪個範圍切（三種填充區域）、切幾刀（Seg. Factor）、刀口怎麼修正（Perpendicular Cut）、要不要貼著房間走（Map HouseHold）」。

「Base Hatch」按 Pick 挑一個封閉填充區域＝整體陽台範圍（欄牆與扶手的外緣判定都靠它，不挑就不會有欄牆/扶手）。
「Balcony Hatch」挑標準陽台可生成的填充區域、「Scenic Balcony Hatch」挑景觀陽台的填充區域（常與 Base 相同，特殊分隔時才不同）。
「Seg. Factor」：每輪隨機切割線的數量（預設 2；值越大切出的塊越多越小）。
「Force Seg.」：使用 Map HouseHold 屋戶切割點時，是否再強制追加 Seg. Factor 條切割線（不勾 Map HouseHold 時，切割線數量恆為 Seg. Factor）。
「Perpendicular Cut」：當切割線與邊界邊呈平行時自動旋轉為垂直切割（預設不勾；勾上可改善窄長邊界的切割成功率）。
「Map HouseHold」：隨機切割點改取自「M3 HouseHold」群組載入的相鄰房間交界（需先「From Watson」成功且模型有對應房間）。
「Ditribute Scenic Balcony」：（介面原始拼法，非拼錯於本手冊）只對 M3 生效——把景觀陽台範圍往固定陽台對側逐步展開分配；M2 中勾選無效果。

💡 Random Level 清單的作用

「Random Level」是 M2/M3 的第二道樓層開關：樓層必須在左側樓層清單與此清單同時勾選才會被隨機分割。預設全勾；要排除某些樓層時在這裡取消勾選即可，不用動主清單。

2.3 生成（Generator 群組 Mode 2 子群組）

📍 右欄「Generator」群組內「Mode 2」子群組：按 Create

一句話：把最近一次 Random 預覽的分割結果建進模型：地板（依 Floor/Wall/扶手勾選項）＋外緣欄牆＋扶手牆。

在「Generator」群組勾選要生成的元素（Floor／Wall／Balcony Handrails／Scenic Handrails，各選類型）。
按 Create，在「Confirm?」對話框答「Yes」。
單一交易建立全部楼层的元素；日誌出現 "Floor Created:ID"、"Wall Created:ID"、"Handrail Created:ID"。完成後回 Revit 逐層檢查。

分頁 3：Mode 3:Along With Curve

沿曲線配置模式：側邊曲線處生成固定深度陽台，其餘範圍隨機；生成內容同模式二（地板＋欄牆＋扶手）。

3.1 隨機預覽（Random）

📍 分頁「Mode 3:Along With Curve」最上方的 Random 按鈕；結果畫在「Preview」群組

一句話：每層在 SideCurve 與該層高程的交點先生成一個「固定陽台」（寬度＝該層抽到的 Gap Factor 值的兩倍、深度＝Fixed Balcony Depth），再把扣除固定陽台（加 Split Depth Extend 過渡區）後的剩餘範圍隨機切割，平面輪廓預覽。

確認已挑樞軸線（直線詳細線）與 SideCurve（模型線，見 3.2）、三種 Hatch 已挑、樓層雙勾完成。
按 Random，「Preview」區逐層顯示；固定陽台會包含在標準陽台（粉紅）輪廓內。
固定陽台位置/深度不合意：調整 SideCurve 位置、Fixed Balcony Depth 或 Split Depth Extend 後再按 Random。

⚠️ M3 的硬前提

M3 預覽一定要有樞軸線與 SideCurve：缺樞軸線報 "No Pivot DetailCurve"（弧線報 "Arc is not supported."）、缺 SideCurve 報 "No Side Curve"、SideCurve 投影不到該層高程報 "SideCurve Projection Failed."——三種訊息都表示該次預覽沒有產生結果。

3.2 側邊曲線與固定陽台（M3 群組）

📍 中欄「M3」群組：「SideCurve」旁的 Pick 按鈕（＋ID 框）、「Fixed Balcony Depth」（500～2000 mm，預設 1100）、「Split Depth Extend」（0～2000 mm，預設 600）

一句話：SideCurve 決定每層固定陽台落在哪，Fixed Balcony Depth 決定它多深，Split Depth Extend 決定固定陽台與景觀區之間保留多寬的過渡。

按「SideCurve」旁的 Pick，在 Revit 中挑一條模型線（Model Line）（提示 "Pick a ModelLine"；M1 勾「Use SideCurve」時也用同一條線）。
設「Fixed Balcony Depth」：固定陽台的深度（mm，預設 1100）。
設「Split Depth Extend」：從固定陽台外緣再往外延伸的過渡距離（mm，預設 600），這段空間會從景觀陽台可用範圍中扣除。

3.3 屋戶資料（M3 HouseHold 群組）

📍 左欄「M3 HouseHold」群組：「Building」下拉（1～20）＋ From Watson 按鈕＋右側紅/綠小圓點指示

一句話：向執行中的 BIM-Watson 程序取回選定編號建築群的「樓層→屋戶→房間」對應，供「Map HouseHold」把隨機切割對齊到房間邊界。

確認 BIM-Watson 程序已開啟並載入同一專案。
選「Building」編號（與 BIM-Watson 中的建築群編號一致），按 From Watson。
成功：右側圓點由紅變綠；失敗（程序未執行、編號不對）圓點保持紅，切割就回退為純隨機。勾「Map HouseHold」（「M2,M3」群組）後生效。

3.4 生成（Generator 群組 Mode 3 子群組）

📍 右欄「Generator」群組內「Mode 3」子群組：按 Create

一句話：把最近一次 Random 預覽的配置（含固定陽台）建進模型，元素組成與模式二相同。

確認「Generator」群組的元素勾選項（Floor/Wall/扶手與類型）。
按 Create，在「Confirm?」對話框答「Yes」。
單一交易建立；固定陽台會併入標準陽台的地板路徑一起建立（日誌 "Floor Created:ID"）。

💡 兩個介面小提醒

①「Mode 3」子群組裡也有「Use Separate Pivot Curve」勾選框，但目前版本的程式碼未使用它——M3 所有樓層一律用主樞軸線，勾與不勾沒有差異（M1 的同名勾選才有效）。

共用控制區（樓層清單、Balcony Limit、Generator、Setting 選單）

以下控制區不在任何分頁內、對三個模式共用，這裡統一說明。

4.1 樓層清單（左欄上方）

📍 左欄最上方的清單，欄名：「Level」（勾選框）、「B. Limit」「S. Limit」（m²，右對齊）、「M1,P3:Piv. Curve」、「」（列尾 Pick 按鈕）

一句話：所有模式的樓層總開關＋分層資訊：勾選要做的樓層、看該層的 Watson 面積上限、給個別樓層指定專屬樞軸線。

勾選要生成陽台的樓層（只列高程大於 0 的樓層；0.00 與地下室不會出現）。
「B. Limit」「S. Limit」顯示該層由「From Watson」取回的標準/景觀陽台面積上限（未取數時為 0）。
要給某層專屬樞軸線：選取該層（可多選）→ 點列尾 Pick → 在 Revit 挑一條直線詳細線；「M1,P3:Piv. Curve」欄填入該詳細線的元素 ID（欄名中的 P3 即 M3）。
取消專屬樞軸線：選取該層後按「Balcony Limit」群組的 M1,M3:Clear Cus. Pivot。

4.2 面積、深度與 Watson 上限（Balcony Limit 群組）

📍 左欄「Balcony Limit」群組：「Balcony Limit」（m²，50～99999，預設 180）＋右側無文字勾選框、「Scenic Limit」（m²，預設 180）＋右側無文字勾選框、「Balcony Dep. Limit」（mm，600～2000，預設 2000）、「Scenic Dep. Limit」（mm，600～3000，預設 3000）、「Use Watson Limit」勾選、「Building」（1～20）＋ From Watson 按鈕＋紅/綠圓點、M1,M3:Clear Cus. Pivot 按鈕

一句話：全模式共用的「陽台做多大量（面積上限、深度）」與「上限從手動值還是 Watson 來」的總設定。

設「Balcony Limit」/「Scenic Limit」：標準/景觀陽台的每層面積上限（m²）。各行右側的無文字小勾選框是該類型的開關：不勾＝該類型不生成（M1 的兩側類型、M2/M3 的兩類分割都會被關掉）。
設「Balcony Dep. Limit」/「Scenic Dep. Limit」：兩種陽台的深度（mm）；M1 的陽台段深度、M2/M3 的切割面積換算都用這兩個值。
要改用法規上限：勾「Use Watson Limit」→ 選「Building」編號 → 按 From Watson（需 BIM-Watson 執行中）。成功後圓點變綠，樓層清單「B. Limit」「S. Limit」填入各層上限；其後預覽/生成都用這些分層值取代上面的 m² 數值。
「From Watson」取回的算法：標準陽台上限＝該層樓地板面積 × 15% − 既有大廳與陽台面積；景觀陽台上限＝樓地板面積 × 12.5% − 既有景觀陽台面積（負值歸零）。

4.3 階段清單（Generator 群組上方）

📍 右欄「Generator」群組左側窄清單，欄名「Phase」

一句話：生成前的必要條件：單選一個階段（預設文件的第一個），沒選會回報 "No Phase Selected."。

在清單中點選要用的階段（單選）。
注意：工具不會把生成元素改歸到所選階段——建立出的元素依 Revit 慣例屬於文件目前的作業階段；此清單主要是必要條件與設定檔記錄用途。

4.4 生成元素選項（Generator 群組上段）

📍 右欄「Generator」群組上段（上→下）：「Basic Balcony」「Scenic Balcony」勾選、「Floor」勾選＋樓板類型下拉＋「Struct.」勾選、「Wall」勾選＋牆體類型下拉＋「Struct.」勾選、「Height」（mm，預設 1200）、「Outline Hatch」勾選＋ Pick、「Handrail Height」（mm，預設 1200）、「Balcony Handrails」勾選＋扶手牆體類型下拉＋偏移（cm，5～50，預設 10）、「Scenic Handrails」勾選＋扶手牆體類型下拉＋偏移（cm，預設 10）、DeleteAll 按鈕

一句話：決定「建哪些元素、用什麼類型、多高多深」——對模式二、三全部生效，對模式一只有 Floor 相關選項有效。

「Basic Balcony」「Scenic Balcony」：兩種陽台類型的生成開關（預設都勾）。
「Floor」＋下拉選樓板類型（從目前模型讀取）：建陽台地板；「Struct.」勾選＝結構地板（僅 Revit 2021 及以下生效）。
「Wall」＋下拉選牆體類型＋「Height」：沿陽台外緣（「Balcony Hatch/Scenic Hatch」減去「Base Hatch」後的邊界）建欄牆；外緣判定需要 Base Hatch，未挑 Base Hatch 不會有欄牆。貼著建築側（落在 Base Hatch 範圍內）的牆段會自動略過。
「Balcony Handrails」「Scenic Handrails」＋類型下拉＋「Handrail Height」＋ cm 偏移：把陽台輪廓往內縮「偏移」公分後，沿其外緣建「扶手牆」（同樣略過落在 Base Hatch 內側的牆段；未挑 Base Hatch 時整組跳過）。
「Outline Hatch」＋ Pick（挑一個填充區域）：勾選後，所有標準陽台的地板路徑會先與該填充區域做聯集、合併成一大片地板（景觀陽台地板不受影響）——常用於把陽台地板與室內地板連成一體。

4.5 刪除本工具所建元素（DeleteAll）

📍 右欄「Generator」群組下段的 DeleteAll 按鈕

一句話：只刪除「本工具記錄在案」的元素：本次工作階段建立的全部，加上已載入設定檔中記錄的 ID；不碰你自己建的東西。

按 DeleteAll，在「Confirm?」對話框答「Yes」。
單一交易刪除；日誌回報完成。若只想復原最近一次 Create，直接在 Revit 按 Ctrl+Z 更快。

⚠️ DeleteAll 的範圍限制

已建元素的 ID 記錄在記憶體與設定檔裡：重開工具視窗後若不 Load/Open 設定檔，之前建的元素就「不在案」，DeleteAll 刪不到。習慣：每完成一批 Create 就「Setting → Save」，讓 ID 記錄進設定檔。

4.6 設定檔管理（Setting 選單）

📍 視窗左上選單「Setting」→「Open」「Load」「Save」「SaveAs」（注意：是「SaveAs」不是「Save As」）

一句話：把目前所有參數（含樓層勾選、Hatch/樞軸線的元素 ID、已建元素 ID 記錄）存成 .bss 設定檔，可重複套用、團隊共享。

「SaveAs」：另存新 .bss 檔案（首次存檔或想保留多套方案用）。
「Save」：存到目前設定檔路徑（還沒選過檔案時會先跳出存檔對話框）。
「Open」：開啟檔案對話框選一個 .bss 設定檔並套用（含恢復已建元素 ID 記錄）。
「Load」：重新載入「目前路徑」那份設定檔（Open/Save 過的）。

💡 設定檔與元素 ID

設定檔記錄的是元素的「數字 ID」。同一檔案若經歷合併/大量刪除，舊 ID 可能指向不存在的元素——載入舊設定檔後若挑取框顯示的 ID 對應元素已被刪，請重新按各「Pick」挑選。

使用技巧與注意事項

名詞對照表

名詞	是什麼	在本工具中的出現位置
樞軸線（Pivot Line）	陽台排列的基準線；工具只接受 Revit「詳細線（Detail Line）」，且必須是直線	「M1,M3」群組；樓層清單的列內專屬樞軸線
法線（Normal）	垂直於樞軸線的平面方向；陽台深度朝法線延伸，「Normal Reverse」可翻轉	「M1,M3」群組的「Normal」顯示值與勾選框
側邊曲線（SideCurve）	決定 M3 固定陽台落點（M1 勾 Use SideCurve 時也用它定起點）的曲線；只能挑「模型線（Model Line）」	「M3」群組
填充區域（Filled Region / Hatch）	Revit 平面中畫的封閉填充元素，工具用它框定生成範圍；挑取提示誤寫 "Pick a DetailLine"	「M2,M3」群組的三列 Hatch、「Generator」的 Outline Hatch
Base / Balcony / Scenic Balcony Hatch	三種用途的填充區域：整體範圍（欄牆/扶手的外緣判定基準）、標準陽台範圍、景觀陽台範圍	「M2,M3」群組
Basic Balcony / Scenic Balcony	標準陽台／景觀陽台（工具生成的兩種陽台類型；預覽圖例：粉紅＝標準、綠＝景觀）	「Generator」勾選、「Balcony Limit」群組、預覽圖例
階段（Phase）	Revit 專案階段；生成前必須已選一個（工具不會改變生成元素的階段歸屬）	「Generator」群組上方的「Phase」清單
樓層（Level）	Revit 樓層；清單只收錄高程大於 0 的樓層	左側樓層清單
Random Level	M2/M3 的第二道樓層開關：兩清單都勾選該層才會被隨機分割	「M2,M3」群組上方的清單
B. Limit / S. Limit	該樓層由 BIM-Watson 取回的標準/景觀陽台面積上限（m²）	樓層清單第 2、3 欄
Watson（BIM-Watson）	同套件的獨立法規檢討程序；「From Watson」向它取面積上限（15% / 12.5% 算法）與屋戶資料，需執行中並載入同一專案	「Balcony Limit」「M3 HouseHold」群組的 From Watson
屋戶（HouseHold）	BIM-Watson 中的戶別分組（樓層→屋戶→房間對應）；讓隨機切割沿房間邊界下刀	「M3 HouseHold」群組＋「M2,M3」的「Map HouseHold」
扶手（Handrails）	本工具的「扶手」實際是以牆體建立（選牆體類型、設高度與內縮偏移），不是 Revit 扶手族	「Generator」群組
設定檔（.bss）	JSON 格式的參數檔，記錄所有設定與已建元素 ID；路徑自動記憶	「Setting」選單
Ditribute Scenic Balcony	介面原始拼法（非本手冊筆誤）：M3 景觀陽台範圍的分配開關，M2 中無效果	「M2,M3」群組
M1,P3:Piv. Curve	欄名中的 P3 即 M3；該欄顯示樓層專屬樞軸線（DetailLine）的元素 ID	樓層清單第 4 欄

高效作業建議

✓ 八則建議

先單層後全部楼层：大型專案先只勾一層「Random → Create」驗證明確，再勾全部楼层一次生成。
預覽可以無限重抽：「Random」純計算不改模型，按到滿意為止；每次結果都不同，多按幾次挑較漂亮的配置。
每批 Create 後立刻 Save 設定檔：讓已建元素 ID 進檔，日後 DeleteAll 才刪得到。
用「B. Limit/S. Limit」分層控量：法規上限隨樓層而異時勾「Use Watson Limit」，別用單一 m² 值硬套全部楼层。
扶手與欄牆記得先挑 Base Hatch：它是外緣判定基準，漏挑就整組消失，事後再補要重做。
窄長填充區配「Perpendicular Cut」：切割線容易被平行邊界卡住（"Maximum Trying Reached."），勾上後成功率明顯提高。
團隊共用 .bss 設定檔：同一專案的標準陽台方案存一份，各層各棟直接 Open，避免參數漂移。
看日誌視窗找原因："Has no available Area. Skip"、"Maximum Trying Reached."、"No Phase Selected." 這些訊息都直接點名問題所在。

重要注意事項

⚠️ 八則警告

批量建立＋刪除都是模型級操作：正式執行前先另存新檔；每次 Create 是單一交易（一次 Ctrl+Z 復原整批），但存檔/繼續編輯後復原即失效。
樞軸線只能是直線詳細線：弧線直接報錯 "Arc is not supported."；挑選時選錯元素類型（如選到模型線）會挑不到或 ID 無效。
模式一不建牆與扶手：Wall/Handrails 選項只對 M2、M3 生效，M1 只做地板。
未挑 Base Hatch＝沒有欄牆、沒有扶手：這是保護邏輯（略過貼建築側的牆段），不是故障。
Revit 2022 以上地板「Struct.」不生效：新版 API 路徑不帶結構旗標，結構屬性以樓板類型為準。
「Mode 3」子群組的「Use Separate Pivot Curve」目前不生效：M3 一律用主樞軸線；只有「Mode 1」子群組的同名勾選有效。
地下一層與 0.00 樓層不會出現在清單：設計上只收錄高程大於 0 的樓層，不是讀取失敗。
「From Watson」需要外部程序：BIM-Watson 未執行或建築群編號不符時圓點保持紅、取數為空（B. Limit/S. Limit 全 0），生成會回退為無上限可依據的 0 值而跳過樓層。

進階應用提示

💡 五種組合玩法

M1 定骨架＋手動補牆：標準住宅用 M1 快速鋪全部楼层地板，欄牆/扶手用 Revit 自訂牆族補，適合有特定欄杆設計的專案。
M2＋Outline Hatch 一體化地板：把陽台地板與室內區域用 Outline Hatch 聯集成單一片樓板，減少樓板碎片、方便後續統一改高程。
M3＋Map HouseHold 戶界對齊：弧形塔樓的固定陽台落點（SideCurve）配合屋戶切割，讓隨機陽台盡量不切穿室內空間。
雙設定檔 A/B 方案：同一棟建物存兩套 .bss（如「全標準陽台」與「標準＋景觀混合」），用 Open 切換比較預覽後再決定正式生成。
分層樞軸線處理退縮造型：外牆逐層退縮的建築，用樓層清單列內 Pick 逐層指定樞軸線＋「Use Separate Pivot Curve」，避免單一樞軸線在退縮層跑位。

常見疑難排解

問題現象	可能原因	解決方法
Create 後沒有任何反應	沒勾任何樓層、階段未選、或面積上限為 0	確認樓層清單勾選、「Phase」清單已選、面積上限大於 0；看日誌視窗的具體訊息（如 "No Phase Selected."）
M1 預覽報 "No Pivot DetailCurve"	還沒挑樞軸線，或原樞軸線被刪除	「M1,M3」群組重新按 Pick 挑一條直線詳細線
報 "Arc is not supported."	樞軸線是弧線	改挑直線詳細線（可先畫一條直的 DetailLine 作基準）
M3 報 "No Side Curve"	「M3」群組還沒挑 SideCurve	按「SideCurve」旁的 Pick 挑模型線（Model Line）
M3 報 "SideCurve Projection Failed."	SideCurve 投影不到該樓層高程（位置太高/太低或離建築太遠）	調整 SideCurve 使其跨越各目標樓層的高程範圍
生成的陽台跑到室內側	法線方向反了	勾「M1,M3」群組的「Normal Reverse」後重新預覽/生成
M1 某樓層預覽沒有陽台	該層面積上限為 0 或過小	日誌會有 "Has no available Area. Skip"；加大「Balcony Limit/Scenic Limit」或改用 Watson 上限
M2/M3 預覽一片空白	對應類型的 Hatch 沒挑、或該類型的開關被取消勾選	確認三列 Hatch 都有 Pick 到封閉填充區域；「Balcony Limit」群組與「Generator」的類型開關都有勾
日誌出現 "Maximum Trying Reached."	隨機切割 512 次仍無法切成合格塊（每塊需至少 1 m²）	加大該類型的面積上限、調低「Seg. Factor」、勾「Perpendicular Cut」，或檢查填充區域是否太窄長/形狀破碎
挑 Hatch 時挑不到、或提示文字很奇怪	只能挑「填充區域」元素；提示誤寫 "Pick a DetailLine"	在平面視圖用填充區域工具畫封閉區域再挑；提示文字是介面問題可忽略
欄牆（Wall）沒生出來	「Wall」沒勾，或未挑「Base Hatch」（外緣判定缺基準）	勾「Generator」的「Wall」＋選牆體類型；先 Pick「Base Hatch」再重新 Random/Create
扶手（Handrails）沒生出來	對應勾選未勾、或未挑「Base Hatch」（無基準時整組牆段都被略過）	勾「Balcony Handrails/Scenic Handrails」、選類型、設「Handrail Height」與偏移；補挑 Base Hatch 後重做
Revit 2022+ 建出的地板不是結構	2022 以上 API 路徑不寫結構旗標	以樓板類型本身決定結構屬性（在類型定義設結構），或降版使用；牆體的「Struct.」不受影響
樓層清單看不到地下室/0.00	設計上只列高程大於 0 的樓層	屬正常現象，無法改變；該類樓層需手動處理
「B. Limit」「S. Limit」全顯示 0	還沒「From Watson」取數，或 BIM-Watson 沒有該樓層資料	勾「Use Watson Limit」、確認 BIM-Watson 執行中且「Building」編號正確、按 From Watson 直到圓點變綠
「From Watson」後圓點仍是紅	BIM-Watson 程序未執行、未載入同一專案、或建築群編號不符	開啟 BIM-Watson 並載入同一專案，核對「Building」編號（1～20）後重按
DeleteAll 刪不到之前生成的元素	重開視窗後未 Load/Open 設定檔，元素 ID 不在案	以後每批 Create 後「Setting → Save」；已不在案的元素請在 Revit 手動選取刪除
載入舊設定檔後挑取框 ID 對應不到元素	設定檔記錄的是元素數字 ID，模型經過大幅改動後 ID 失效	重新按各 Pick 挑選樞軸線/側邊曲線/填充區域，再 Save 覆蓋設定檔
生成結果與預覽長得不一樣	Create 前又按過其他分頁的 Random（預覽是「最近一次」的），或兩類開關中途變動	先按該分頁 Random 重新預覽，確認後立刻 Create，中間不要再改勾選項
M3 固定陽台位置/大小不合預期	SideCurve 位置、Gap Factor 間距或 Fixed Balcony Depth 影響落點與尺寸	調整 SideCurve 線位、縮小/放大「Gap Factor」範圍、「Fixed Balcony Depth」後重新 Random
M3 固定陽台與景觀區交接處不自然	Split Depth Extend 過小（過渡區不夠）或過大（佔掉景觀面積）	調整「Split Depth Extend」（預設 600 mm）後重新預覽
工具視窗突然關閉	Revit 檔案被關閉（工具視窗隨文件關閉）	重新開啟檔案並執行 Balcony Shaper 指令即可；參數可用「Setting → Open」載回
M2/M3 預覽只出現部分樓層	樓層必須在「樓層清單」與「Random Level」清單同時勾選	核對兩份清單的勾選狀態，把該補的樓層補勾後再按 Random
各 Pick 旁的 ID 框顯示 0	尚未挑選元素（0＝未選取）	按對應的 Pick 到 Revit 挑選；ID 會自動填入該框
Load/Open 設定檔後勾選狀態與記憶中不同	設定檔會以儲存時的樓層/階段勾選覆蓋目前視窗狀態	載入後先核對樓層清單與 Phase 清單的勾選，再執行 Random/Create

快速查詢：遇到什麼狀況用什麼功能

我想要…	用這個功能（所在分頁）
標準住宅沿外牆排一致的陽台	Mode 1 分頁＋「M1,M3」群組樞軸線（分頁 1）
陽台生成方向朝室內，翻到室外	「M1,M3」群組「Normal Reverse」（分頁 1）
某些樓層用不同的樞軸線	樓層清單列內 Pick＋「Generator/Mode 1」的「Use Separate Pivot Curve」（分頁 1、共用 4.1）
取消某層的專屬樞軸線	選取該層→「Balcony Limit」群組 M1,M3:Clear Cus. Pivot（共用 4.1/4.2）
立面要隨機變化的陽台配置	Mode 2 分頁＋三列 Hatch（分頁 2）
弧形外牆、邊緣固定深度陽台	Mode 3 分頁＋SideCurve/Fixed Balcony Depth（分頁 3）
生成前先看配置	各分頁的 Random 預覽（可無限重抽）
陽台太大/太小（面積）	「Balcony Limit」群組「Balcony Limit / Scenic Limit」（m²，共用 4.2）
陽台太深/太淺	「Balcony Limit」群組「Balcony Dep. Limit / Scenic Dep. Limit」（mm，共用 4.2）
陽台面積要符合法規（分樓層上限）	「Use Watson Limit」＋「From Watson」（共用 4.2）
外緣加欄牆	「Generator」勾「Wall」＋類型＋「Height」，且已挑 Base Hatch（分頁 2/3）
加扶手（欄杆）	「Generator」勾「Balcony Handrails / Scenic Handrails」＋「Handrail Height」＋cm 偏移（分頁 2/3）
陽台地板要結構	「Generator」Floor 的「Struct.」（僅 Revit 2021 及以下生效）
標準陽台地板與室內地板連成一體	「Generator」勾「Outline Hatch」＋Pick 挑填充區域（分頁 2/3）
只生成一種陽台（只要標準或只要景觀）	取消「Generator」對應勾選、或「Balcony Limit」群組該行右側的無文字開關
只生成地板、不要牆	取消「Generator」的「Wall」與兩個 Handrails 勾選
隨機切塊太多/太少	「M2,M3」群組「Seg. Factor」（1～5，分頁 2）
切割線卡在平行邊界	「M2,M3」群組「Perpendicular Cut」（分頁 2）
切割要貼著戶與戶之間	「M3 HouseHold」From Watson＋「M2,M3」勾「Map HouseHold」（分頁 3、共用）
景觀陽台範圍均勻展開（M3）	「M2,M3」群組「Ditribute Scenic Balcony」（分頁 3 生效）
M1 兩側類型固定（不隨機）	取消「M1」群組「Random Balcony Type」（起始側標準、對側景觀）
把一套參數存起來共用	「Setting」選單 SaveAs / Save / Open / Load（共用 4.6）
整批復原剛生成的陽台	Revit 中按一次 Ctrl+Z（每次 Create 為單一交易）
刪除所有本工具建出的元素	「Generator」DeleteAll（Confirm 確認，共用 4.5）
預覽顏色代表什麼	「Preview」區下方圖例：綠「=Scenic Balcony」、粉紅「=Basic Balcony」

功能索引表（依分頁）

分頁	包含功能	典型產出
Mode 1:Single Side Pattern	Random 預覽（立面）；M1 群組（Max. Pattern、Random Balcony Type、Balcony Type Reverse、Use SideCurve）；M1,M3 群組（Pivot Line Pick、Normal Reverse、Gap Factor、Smooth Gap/Smooth Factor）；Generator/Mode 1（Use Separate Pivot Curve、Create）	各樓層陽台地板（可分層專屬樞軸線）
Mode 2:Range Random	Random 預覽（平面）；M2,M3 群組（Random Level 清單、Base/Balcony/Scenic Balcony Hatch Pick、Seg. Factor、Force Seg.、Map HouseHold、Perpendicular Cut、Ditribute Scenic Balcony）；Generator/Mode 2（Create）	各樓層隨機分割的陽台地板＋欄牆＋扶手
Mode 3:Along With Curve	Random 預覽（平面）；M3 群組（SideCurve Pick、Fixed Balcony Depth、Split Depth Extend）；M3 HouseHold 群組（Building、From Watson）；Generator/Mode 3（Create）	各樓層固定陽台＋隨機陽台的地板＋欄牆＋扶手
共用控制區	樓層清單（勾選、B./S. Limit、列內 Pick 專屬樞軸線）；Balcony Limit 群組（面積/深度上限、Use Watson Limit、From Watson、M1,M3:Clear Cus. Pivot）；Phase 清單；Generator 上段（Basic/Scenic Balcony、Floor/Wall＋Struct.、Height、Outline Hatch、Handrail Height、兩種 Handrails）；DeleteAll；Setting 選單（Open/Load/Save/SaveAs）	參數與範圍設定、元素建立選項、設定檔、刪除

常用工作流

標準住宅全流程（M1）

勾樓層 →「M1,M3」挑樞軸線 → 核對「Balcony Limit」面積/深度 → 分頁 1「Random」預覽 →「Normal Reverse」修正方向 →「Generator/Mode 1」Create → Ctrl+Z 或 DeleteAll 復原試錯。

立面變化高樓（M2）

三列 Hatch 挑好（Base 一定要）→「M2,M3」調 Seg. Factor/Perpendicular Cut → 勾樓層＋Random Level → 分頁 2「Random」重抽到滿意 →「Generator」勾 Floor/Wall/Handrails →「Mode 2」Create。

弧形外牆（M3）

「M3」挑 SideCurve＋設 Fixed Balcony Depth/Split Depth Extend → 三列 Hatch → 分頁 3「Random」預覽固定陽台落點 →「Mode 3」Create。

法規連動（Watson）

確認 BIM-Watson 執行中 →「Balcony Limit」勾「Use Watson Limit」＋選 Building→「From Watson」至圓點變綠 → 檢查樓層清單「B. Limit/S. Limit」→ 預覽/生成。

屋戶對齊切割

「M3 HouseHold」選 Building＋「From Watson」→ 勾「M2,M3」的「Map HouseHold」→（選）「Force Seg.」→ 分頁 2/3「Random」預覽，刀口沿房間交界。

團隊設定檔

參數調好 →「Setting → SaveAs」存 .bss → 團隊成員「Setting → Open」載入 → 各自 Random 預覽確認 → Create。

清理與重來

結果不合：整批 → Revit Ctrl+Z（單一交易）；跨批次 →「Generator」DeleteAll（需在案的 ID）→ 改參數 →「Random」→ Create。記得每批後「Setting → Save」。