v1.20-for-beta43

Author: sigma-axis

@Path_S.anm2

@@ -1,4 +1,3 @@
--- under development for v1.20 (for beta42) r7
 --[[
 MIT License
 Copyright (c) 2025-2026 sigma-axis
@@ -24,7 +23,7 @@ SOFTWARE.
 https://mit-license.org/
 ]]
 @パスマスクσ
---information:パスマスクσ@Path_S v1.12 (for beta25) by σ軸
+--information:パスマスクσ@Path_S v1.20 (for beta43) by σ軸
 --label:Path_S\クリッピング
 --filter
 --require:2004001
@@ -217,7 +216,7 @@ else
 end
 
 @パスマスク(ライン)σ
---information:パスマスク(ライン)σ@Path_S v1.12 (for beta25) by σ軸
+--information:パスマスク(ライン)σ@Path_S v1.20 (for beta43) by σ軸
 --label:Path_S\クリッピング
 --filter
 --require:2004001
@@ -490,7 +489,7 @@ else
 end
 
 @パス部分フィルタσ
---information:パス部分フィルタσ@Path_S v1.12 (for beta25) by σ軸
+--information:パス部分フィルタσ@Path_S v1.20 (for beta43) by σ軸
 --label:Path_S\加工
 --require:2004001
 --check@invert:反転,false
@@ -662,7 +661,7 @@ if extra_filter == 0 then
 end
 
 @パスに沿って配置σ
---information:パスに沿って配置σ@Path_S v1.12 (for beta25) by σ軸
+--information:パスに沿って配置σ@Path_S v1.20 (for beta43) by σ軸
 --label:Path_S\配置
 --require:2004001
 --track@position:位置,-400,400,0,0.001,,0.25

@Path_S.obj2

@@ -1,4 +1,3 @@
--- under development for v1.20 (for beta42) r8
 --[[
 MIT License
 Copyright (c) 2025-2026 sigma-axis
@@ -24,7 +23,7 @@ SOFTWARE.
 https://mit-license.org/
 ]]
 @パス図形σ
---information:パス図形σ@Path_S v1.12 (for beta25) by σ軸
+--information:パス図形σ@Path_S v1.20 (for beta43) by σ軸
 --label:Path_S\図形
 --require:2004001
 --track@line:ライン幅,0,1000,5,0.01,,0.2
@@ -224,7 +223,7 @@ if has_fill or has_chrome then
 end
 
 @ラインσ
---information:ラインσ@Path_S v1.12 (for beta25) by σ軸
+--information:ラインσ@Path_S v1.20 (for beta43) by σ軸
 --label:Path_S\図形
 --require:2004001
 --track@X:終点X,-4000,4000,256,0.01,,0.25
@@ -439,7 +438,7 @@ path_s.path_mask_line(
 	1, 0, obj.cx, obj.cy);
 
 @スパイラルσ
---information:スパイラルσ@Path_S v1.12 (for beta25) by σ軸
+--information:スパイラルσ@Path_S v1.20 (for beta43) by σ軸
 --label:Path_S\図形
 --require:2004001
 --track@start_radius:開始半径,0,2000,0,0.01,,0.25
@@ -619,7 +618,7 @@ path_s.path_mask_line(
 	1, 0, obj.cx, obj.cy);
 
 @アローσ
---information:アローσ@Path_S v1.12 (for beta25) by σ軸
+--information:アローσ@Path_S v1.20 (for beta43) by σ軸
 --label:Path_S\図形
 --require:2004001
 --track@line:ライン幅,0,1000,5,0.01,,0.2
@@ -878,7 +877,7 @@ end
 obj.cx, obj.cy = cx, cy;
 
 @スクウェアσ
---information:スクウェアσ@Path_S v1.12 (for beta25) by σ軸
+--information:スクウェアσ@Path_S v1.20 (for beta43) by σ軸
 --label:Path_S\図形
 --require:2004001
 --track@width:幅,0,4000,100,0.01,,0.25

Path_S.lua

@@ -1,4 +1,3 @@
--- under development for v1.20 (for beta42) r8
 --[[
 MIT License
 Copyright (c) 2025-2026 sigma-axis
@@ -25,7 +24,7 @@ https://mit-license.org/
 ]]
 
 --
--- v1.12 (for beta25)
+-- v1.20 (for beta43)
 --
 
 local obj, print, math, tonumber, ipairs, unpack, bit, ffi, buffer = obj, print, math, tonumber, ipairs, unpack, bit, require("ffi"), require("string.buffer");
@@ -66,41 +65,48 @@ local anchor, poll do
 	---@param pts { [integer]: number? } 点列の配列， `{ x1, y1, x2, y2, x3, y3, ... }` の形式．
 	---@param n_segs integer パスの分割区間の個数．
 	---@param loop boolean 閉じたパスかどうか．
+	---@param alt_points function? `alt_pts = alt_points(path_type, pts, n_segs, loop)` 想定されるアンカーの個数が `pts` の点の個数と異なる場合に呼ばれる関数．代替となる点列テーブルを返す．省略時は独自の方法で代替の点列を構築する．
 	---@return integer n_anchors 設定したアンカーの個数．
 	---@return table pts_corrected 足りない点や余剰な点を補正した点列．補正の必要がない場合は `pts` そのもの．
-	function anchor(var_name, path_type, pts, n_segs, loop)
+	function anchor(var_name, path_type, pts, n_segs, loop, alt_points)
 		local pts_per_seg =
 			path_type == 0 and 1 or
 			path_type == 1 and 1 or
 			path_type == 2 and 2 or 3;
 		local n_anchors = (loop and 0 or 1) + pts_per_seg * n_segs;
 		local alt_pts = nil;
 		if 2 * n_anchors ~= #pts then
-			alt_pts = {};
-			local n = math.min(n_anchors, math.floor(#pts / 2));
-			for i = 1, 2 * n do alt_pts[i] = pt(pts, i) end
-
-			if n < n_anchors then
-				-- find a suitable placeholder point.
-				local k = 1 + math.floor((n - 1) / pts_per_seg) * pts_per_seg;
-				local X, Y = pt(pts, 2 * k - 1), pt(pts, 2 * k); -- last point.
-				local dx, dy;
-				if loop then
-					dx, dy = (pt(pts, 1) - X) / 2, (pt(pts, 2) - Y) / 2;
-				else
-					k = math.max(1, k - pts_per_seg);
-					dx, dy = (X - pt(pts, 2 * k - 1)) / 2, (Y - pt(pts, 2 * k)) / 2;
-				end
-				local l = dx ^ 2 + dy ^ 2;
-				if l > 100 ^ 2 then
-					l = 100 / l ^ 0.5; -- at most 100 pixel far.
-					dx, dy = l * dx, l * dy;
-				end
-				X, Y = X + dx, Y + dy;
+			if alt_points then
+				alt_pts = alt_points(path_type, pts, n_segs, loop);
+				if 2 * n_anchors ~= #alt_pts then alt_pts = nil end
+			end
+			if alt_pts == nil then
+				alt_pts = {};
+				local n = math.min(n_anchors, math.floor(#pts / 2));
+				for i = 1, 2 * n do alt_pts[i] = pt(pts, i) end
+
+				if n < n_anchors then
+					-- find a suitable placeholder point.
+					local k = 1 + math.floor((n - 1) / pts_per_seg) * pts_per_seg;
+					local X, Y = pt(pts, 2 * k - 1), pt(pts, 2 * k); -- last point.
+					local dx, dy;
+					if loop then
+						dx, dy = (pt(pts, 1) - X) / 2, (pt(pts, 2) - Y) / 2;
+					else
+						k = math.max(1, k - pts_per_seg);
+						dx, dy = (X - pt(pts, 2 * k - 1)) / 2, (Y - pt(pts, 2 * k)) / 2;
+					end
+					local l = dx ^ 2 + dy ^ 2;
+					if l > 100 ^ 2 then
+						l = 100 / l ^ 0.5; -- at most 100 pixel far.
+						dx, dy = l * dx, l * dy;
+					end
+					X, Y = X + dx, Y + dy;
 
-				-- fill the rest with that placeholder.
-				for i = n + 1, n_anchors do
-					alt_pts[2 * i - 1], alt_pts[2 * i] = X, Y;
+					-- fill the rest with that placeholder.
+					for i = n + 1, n_anchors do
+						alt_pts[2 * i - 1], alt_pts[2 * i] = X, Y;
+					end
 				end
 			end
 		end

README.md

@@ -38,7 +38,7 @@
 
   http://spring-fragrance.mints.ne.jp/aviutl
 
-  - `beta25` で動作確認済み．
+  - `beta43` で動作確認済み．
 
 ## 導入方法
 
@@ -322,8 +322,6 @@ Although, usage documentations for this script / plugin in languages other than
 
 ### パス図形σのパラメタ
 
-![Image of GUI of Figure](https://github.com/user-attachments/assets/db98e5eb-91c7-4956-a62e-d0cef192d3c7)
-
 ####  ライン色, ライン透明度
 
 図形のライン部分の色と透明度を指定します．
@@ -341,8 +339,6 @@ Although, usage documentations for this script / plugin in languages other than
 
 ### ラインσのパラメタ
 
-![Image of GUI of Curve](https://github.com/user-attachments/assets/1bbc84af-bd0c-4cbb-9315-f648c3c2ba96)
-
 ####  終点X, 終点Y
 
 ラインの終点の X, Y 座標を指定します (始点はオブジェクトの標準描画等の指定座標です).
@@ -386,8 +382,6 @@ Although, usage documentations for this script / plugin in languages other than
 
 ### スパイラルσのパラメタ
 
-![Image of GUI of Spiral](https://github.com/user-attachments/assets/a44b065a-82d1-47da-9de6-10425c82f65a)
-
 ####  傾き
 
 螺旋の半径に対する角度の移動量の比率を調整します．厳密な解釈は[「形状」](#形状-1)によって異なりますが，数値 (の絶対値) が大きいほど回転回数が大きくなります．負になると回転方向が逆転します．
@@ -441,8 +435,6 @@ Although, usage documentations for this script / plugin in languages other than
 
 ### アローσのパラメタ
 
-![Image of GUI of Arrow](https://github.com/user-attachments/assets/e878b7c9-801c-4b10-b29a-2b88e091c4db)
-
 ####  色
 
 矢印図形の色を指定します．
@@ -496,8 +488,6 @@ Although, usage documentations for this script / plugin in languages other than
 
 ### スクウェアσのパラメタ
 
-![Image of GUI of Round Rect](https://github.com/user-attachments/assets/2daa8080-8816-4b6f-a0ab-51ae1173fa6c)
-
 ####  幅, 高さ
 
 四角形の幅と高さをピクセル単位で指定します．実際のオブジェクトのサイズは，ライン幅やぼかし幅などでこの数値よりも大きくなります．
@@ -564,10 +554,6 @@ Although, usage documentations for this script / plugin in languages other than
 
 ### パスマスクσ / パスマスク(ライン)σ / パス部分フィルタσのパラメタ
 
-![Image of GUI of Clip by Path (Area)](https://github.com/user-attachments/assets/744a1c17-3c34-4b7c-a2b3-c9bbec823827)
-![Image of GUI of Clip by Path (Line)](https://github.com/user-attachments/assets/19a729f3-da7d-4ed7-ba49-4ab53aebc74a)
-![Image of GUI of Partial Filter by Path](https://github.com/user-attachments/assets/0ac4089e-ce38-47ad-84d1-a44e2222d2e8)
-
 ####  強さ
 
 *「パスマスクσ」と「パスマスク(ライン)σ」のみの項目です．*
@@ -632,8 +618,6 @@ obj.cx=obj.cx+100 -- 位置もずらせる
 
 ### パスに沿って配置σのパラメタ
 
-![Image of GUI of Place Along Path](https://github.com/user-attachments/assets/5e828666-1ee6-479b-adbf-e292274b6a8d)
-
 ####  位置
 
 オブジェクトを配置する位置を，パス全体の長さからの割合で % 単位で指定します．[「ループ」](#ループ)が ON の場合，0 % を下回った分はパスの終了点から，100 % を上回った分はパスの開始点からカウントされます．
@@ -866,10 +850,15 @@ radii = { uniform = 10; { 16, 8 }, nil, 20, nil }
   X = num, Y = num, -- number 型で "移動X", "移動Y" の項目を上書き，または nil.
   zoom = num,       -- number 型で "拡大率" の項目を上書き，または nil.
   rotate = num,     -- number 型で "回転" の項目を上書き，または nil.
+
+-- 以降は require("Path_S") からの API で代替できるようになったため非推奨です．
   pt_buff = str,    -- string 型で, パスの頂点情報を保持している画像バッファ名を指定，または nil. 詳細後述．
 }
 ```
 
+<details>
+<summary>v1.12 以前の「パス図形σ」などで内部的に使われていましたが，現在は非推奨な項目の解説です:</summary>
+
 フィールド `.pt_buff` は `"tempbuffer"` か `"cache:****"` の形式の文字列で，`Path_S.lua` の `.send()` 関数によって頂点情報が保持されている画像バッファ名を指定します．この場合，次に注意してください:
 1.  「頂点数」または `.num_points` にはこのバッファに保持された点の個数を指定すること．
 1.  次のパラメタやフィールドは無視されます:
@@ -880,7 +869,7 @@ radii = { uniform = 10; { 16, 8 }, nil, 20, nil }
     1.  「拡大率」と `.zoom`.
     1.  「回転」と `.rotate`.
 1.  指定された頂点は折れ線と解釈して描画されます．
-
+</details>
 
 ####  パスマスク(ライン)σの `PI`
 
@@ -904,12 +893,17 @@ radii = { uniform = 10; { 16, 8 }, nil, 20, nil }
   X = num, Y = num, -- number 型で "移動X", "移動Y" の項目を上書き，または nil.
   zoom = num,       -- number 型で "拡大率" の項目を上書き，または nil.
   rotate = num,     -- number 型で "回転" の項目を上書き，または nil.
+
+-- 以降は require("Path_S") からの API で代替できるようになったため非推奨です．
   pt_buff = str,    -- string 型で, パスの頂点情報を保持している画像バッファ名を指定，または nil. 詳細後述．
   len_buff = num,   -- number 型で, パス全体のピクセル長を指定，または nil. 詳細後述．
   endpt_buff = tab, -- table 型で, パスの両端の座標と方向を記述，または nil. 詳細後述．
 }
 ```
 
+<details>
+<summary>v1.12 以前の「パス図形σ」などで内部的に使われていましたが，現在は非推奨な項目の解説です:</summary>
+
 フィールド `.pt_buff` は `"tempbuffer"` か `"cache:****"` の形式の文字列で，`Path_S.lua` の `.send()` 関数によって頂点情報が保持されている画像バッファ名を指定します．この場合，次に注意してください:
 1.  「頂点数」または `.num_points` にはこのバッファに保持された点の個数を指定すること．
 1.  `.len_buff` にはパス全体のピクセル長を指定すること．
@@ -936,7 +930,7 @@ radii = { uniform = 10; { 16, 8 }, nil, 20, nil }
 1.  指定された頂点は折れ線と解釈して描画されます．
 
 `.pt_buff` が `nil` の場合は，`.len_buff` と `.endpt_buff` は無視されます．
-
+</details>
 
 ####  パス部分フィルタσの `PI`
 
@@ -974,6 +968,13 @@ radii = { uniform = 10; { 16, 8 }, nil, 20, nil }
 }
 ```
 
+##  同梱のスクリプトファイル `Path_S.lua` について
+
+他スクリプトからの利用も想定したものになっていて，`local path_s = require("Path_S")` から各種 API を呼び出せます．
+
+「パスマスクσ」「パスマスク(ライン)σ」に関しては `obj.effect(...)` を使わずとも `path_s.path_mask_area(...)` や `path_s.path_mask_line(...)` から適用できます．各種パスの曲線を折れ線に変換するなどといった API も用意しています．
+
+`Path_S.lua` にドキュメントコメントを残しているので，詳しい仕様はそちらを参照してください．
 
 ##  既知の問題
 
@@ -983,9 +984,9 @@ radii = { uniform = 10; { 16, 8 }, nil, 20, nil }
 
 1.  [「パス部分フィルタσ」](#パス部分フィルタσ)で「後続フィルタ」を指定するものは，1つのオブジェクトに対して複数設定できません (つまり「入れ子」のような構造は指定不可能).
 
-##  次の改版予定
+##  改版履歴
 
-- **v1.20 (for beta42)** (2026-??-??)
+- **v1.20 (for beta43)** (2026-04-26)
 
   - 「パス部分フィルタσ」で後続フィルタの代わりにスクリプトの直接記入をできるように．
   - 3次ベジェ曲線のアンカーのハンドルを色分けして表示するように．
@@ -1007,8 +1008,6 @@ radii = { uniform = 10; { 16, 8 }, nil, 20, nil }
 
   - `beta42` での動作確認．
 
-##  改版履歴
-
 - **v1.12 (for beta25)** (2025-12-22)
 
   - 「パスマスクσ」と「パスマスク(ライン)σ」をフィルタオブジェクトとして使えるように設定．