コンテンツにスキップ
AUTD3 SDK
starlightVersions.search.outdated.slug starlightVersions.search.link.latest

FociStm

FociStm は, ハードウェアタイマにより単一, 及び, 多焦点音場を切り替える STM 機能を提供する. PatternStm と異なり, 焦点しか扱えないが, 1フレームに複数の焦点情報を乗せされるためフレーム数が少なく, レイテンシが小さい.

API

Section titled “API”
FociStm::new(freq, &points, option);
引数 型 説明
freq impl Into<StmConfig> 再生レート (Freq / Duration / SamplingConfig)
points &[ControlPoints<N>] 焦点サンプルの列 (2 サンプル以上)
option FociStmOption 音速・ループ・遷移などのオプション

freq に Freq / Duration を渡すと「全サンプルを 1 周する周波数/周期」を表す. サンプリング周波数を指定することもできる. Duration がサンプル数で割り切れない場合はエラーになる (丸めたいときは Nearest を使う).

ControlPoint / ControlPoints

Section titled “ControlPoint / ControlPoints”

1 サンプルは ControlPoints<N> で表される. N は同時に出す焦点の数 (最大 8) である.

  • ControlPoint { point, phase_offset } — 焦点座標 [mm] と位相オフセット.
  • ControlPoints<N> { points: [ControlPoint; N], intensity } — N 個の焦点と振幅.

FociStmOption

Section titled “FociStmOption”
FociStmOption {
    bank,
    sound_speed,
    loop_behavior,
    transition_mode,
}
フィールド 型 デフォルト 説明
bank PatternBank PatternBank::B0 書き込み先・再生対象のバンク
sound_speed Velocity 340 m/s 焦点計算に使う音速
loop_behavior LoopBehavior LoopBehavior::Infinite ループ回数
transition_mode TransitionMode TransitionMode::Immediate バンク切替時の遷移タイミング

loop_behavior と transition_mode の挙動は再生制御 を参照.

ヘルパ関数

Section titled “ヘルパ関数”

典型的な軌道を生成するヘルパ関数が用意されている.

circle

Section titled “circle”
circle(center, radius, num_points, normal, intensity, &mut dst);
引数 型 説明
center Point3<f32> 円の中心 [mm]
radius Length 円の半径
num_points usize 生成する点の数
normal UnitVector3<f32> 円平面の法線 (単位ベクトル)
intensity Intensity 各点の振幅
dst &mut Vec<ControlPoints<1>> 出力バッファ

normal を法線とする円周上に等間隔で num_points 個の点を並べる.

line

Section titled “line”
line(start, end, num_points, intensity, &mut dst);
引数 型 説明
start Point3<f32> 始点 [mm]
end Point3<f32> 終点 [mm]
num_points usize 生成する点の数
intensity Intensity 各点の振幅
dst &mut Vec<ControlPoints<1>> 出力バッファ

始点・終点を含む等間隔の直線上に num_points 個の点を並べる.

等価な低レベルコマンド

Section titled “等価な低レベルコマンド”

FociStm は WriteFociBuffer + ConfigFociStm + ChangePatternBank の 3 つと等価である. データが 1 フレームに収まる場合は融合して 1 フレームで送られ, 収まらない場合は上記の 3 コマンドに展開される. 以下は FociStm::new(freq, &points, option) と等価な組み合わせである.

WriteFociBuffer {
    bank: option.bank,
    index_offset: 0,
    points: &points,
};
ConfigFociStm {
    bank: option.bank,
    config: StmConfig::new(freq).into_sampling_config(points.len()),
    size: points.len(),
    num_foci: N, // N is the number of foci in the points
    sound_speed: option.sound_speed,
    loop_behavior: option.loop_behavior,
};
ChangePatternBank {
    bank: option.bank,
    transition_mode: option.transition_mode,
};

Example

Section titled “Example”
use autd3_rs::commands::{FociStm, FociStmOption, circle};
use autd3_rs::geometry::{Autd3, Geometry, Vector3, offset};
use autd3_rs::units::{Hz, m, mm, s};
use autd3_rs::value::{Intensity, LoopBehavior, PatternBank, TransitionMode};
use autd3_rs::{Client, ClientConfig};
use autd3_rs_link_nop::Nop;


let geometry = Geometry::new(vec![Autd3::default()]);
let client = Client::open(&geometry, Nop, ClientConfig::default()).await?;


let center = geometry.center() + offset(0.0 * mm, 0.0 * mm, 150.0 * mm);
let mut points = Vec::new();
circle(
    center,
    30.0 * mm,
    200,
    Vector3::z_axis(),
    Intensity::MAX,
    &mut points,
);


let mut builder = client.datagram_builder();
builder.push(FociStm::new(
    1.0 * Hz,
    &points,
    FociStmOption {
        bank: PatternBank::B0,
        sound_speed: 340.0 * m / s,
        loop_behavior: LoopBehavior::Infinite,
        transition_mode: TransitionMode::Immediate,
    },
));
let frames = builder.build()?;
for frame in &frames {
    client.send_checked(frame).await?;
}


client.close().await?;