annotate_text_path_layout — ANNOTATE `paper` op

• 資料種類:text → table

• 呼叫: import fullseye as fs; fs.ledger.annotate_text_path_layout(text, path, font_size=13, font_path=None, spacing=1.0, start=0.0, anchor='start', offset=0.0, upright=False, line_spacing=1.15)(要直接呼叫實作,import annotate; annotate.annotate_text_path_layout(text, path, font_size=13, font_path=None, spacing=1.0, start=0.0, anchor='start', offset=0.0, upright=False, line_spacing=1.15);從台帳取用則 opsannotate.get("annotate_text_path_layout"))

用法

回傳表(dict):沿折線逐字的位置與傾角(按弧長確定)。

第 i 個字元的中心位於弧長 s_i = s0 + Σ_{j<i} a_j*spacing + a_i/2 處,傾斜為該位置線段的切線角(螢幕座標,度)。比路徑長的字串會引發 ValueError。

位置的決定方式(2026-09-08 新增。預設與此前的行為相同):

• anchor —— 沿路徑的對齊方式。"start"(預設、與以往相同)/ "center"(對齊到路徑中央)/ "end"(對齊到終端)。start 作為從錨點決定的位置再偏移的量起作用。

• offset —— 與路徑垂直的偏移 [px]。正方向為前進方向的右側 (螢幕座標。y 朝下,所以對於從左→右排列的文字就是「下」)。用於不碰線而放在旁邊。

• 用 \n 換行。第 2 行及以後按乘以 line_spacing 的行高, 向與 offset 相同的方向(前進方向的右側)偏移。★憑這 1 條規則, 橫排「向下」、直排「向左」,都符合排版規範 (直排的前進方向朝下,所以它的右側就是螢幕的左側)。

• upright —— 不把字元轉到切線角,而是保持正立。若路徑主要為縱向(起點→終點的 |dy| > |dx|),則步進量用字高而不是字寬, 這就成為直排。只有 VERTICAL_ROTATED_CHARS 中的字元旋轉 90 度。

標點(、。，．)按直排的規範向右上靠 (VERTICAL_SHIFTED_CHARS,偏移量為步進量的 _VPUNCT_SHIFT 倍)。Windows 中帶 @ 的字型在字型端所做的事,這裡用合成來完成 —— Pillow 按檔案路徑開啟字型,無法到達 @ 字面, HarfBuzz 的 direction="ttb" 結果也會因有無 Raqm 而變化, 所以採用了在各平台上一致的方式。

★直排中未實作的內容(不默默近似):小寫假名的位置修正、縱中橫、行末禁則。這是為簡短註記準備的功能,不是正文排版。

Returns

dict

{"chars": [{"char","s","xy","angle_deg","width","advance","line"}], "length": 路徑長, "used": 最長一行的**步進量總和**(與以往相同 Σ advance*spacing), "span": 最長一行**實際佔據**的弧長(不含最後一個字元之後的步進量 —— 錨點按這個對齊), "lines": 行數, "line_height": 行距 [px], "vertical": 是否直排}。

Raises

ValueError

文字為空、路徑少於 2 點或長度為零、非有限、某行比路徑長、

錨點與 start 的組合使某行超出路徑的情況。

詳細使用指南

• figure_annotation 族使用指南

背景知識指南(該運算子背後的物理與規範)

• dataset_conventions — 訓練資料集規範知識 —— COCO / YOLO / VOC 及外觀檢測中的陷阱

參考(範例資料、文獻)

• 範例資料目錄(下載 URL / 授權) —— 2-D 用 skimage.data(BSD/公有領域)加合成圖,3-D 給出真實資料源(Stanford/PDS 等)的下載 URL。

• 運算子來歷與參考文獻 —— 該運算子族所依據的研究/方法出處。

• 演算法的正典(作者、年份)與用途見上面的族使用指南。

可執行的範例(實際呼叫該運算子並已驗證的樣例)

• annotate_paper_tour — py -3.11 examples/annotate_paper_tour.py

型別可銜接的下一個運算子(可接受 `table` 作為輸入)

—

同類別(`paper`)

annotate_leader_layout · annotate_leader · annotate_markers · annotate_legend · annotate_dimension_layout · annotate_dimension · annotate_angle_layout · annotate_angle

*Provenance: annotate.py — ANNOTATE 運算子登記表。本條目由 tools/opdocs.py md 自動產生(請勿手動編輯)。*

annotate_text_path_layout — ANNOTATE paper op

用法