autd3-core 38.1.0

AUTD3 core traits and types
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

mod error;
mod filter;

pub use error::GainError;
pub use filter::{DeviceTransducerMask, TransducerMask};

use crate::{
    datagram::DeviceMask,
    environment::Environment,
    firmware::Drive,
    firmware::{Segment, transition_mode::TransitionModeParams},
    geometry::{Device, Geometry, Transducer},
};

/// A trait to calculate the phase and intensity for each [`Transducer`].
///
/// [`Gain`]: crate::gain::Gain
pub trait GainCalculator<'a>: Send + Sync {
    /// Calculates the phase and intensity for the given [`Transducer`].
    #[must_use]
    fn calc(&self, tr: &'a Transducer) -> Drive;
}

impl<'a> GainCalculator<'a> for Box<dyn GainCalculator<'a>> {
    fn calc(&self, tr: &'a Transducer) -> Drive {
        self.as_ref().calc(tr)
    }
}

/// A trait for generating a [`GainCalculator`].
pub trait GainCalculatorGenerator<'a> {
    /// The type of [`GainCalculator`].
    type Calculator: GainCalculator<'a>;

    /// Generate a [`GainCalculator`] for the given [`Device`].
    #[must_use]
    fn generate(&mut self, device: &'a Device) -> Self::Calculator;
}

/// A trait for intensity/phase calculation.
///
/// See also [`Gain`] derive macro.
///
/// [`Gain`]: autd3_derive::Gain
pub trait Gain<'a>: Sized {
    /// The type of [`GainCalculatorGenerator`].
    type G: GainCalculatorGenerator<'a>;

    /// Initialize the gain and generate [`GainCalculatorGenerator`].
    ///
    /// `filter` represents the enabled/disabled state of each transducer.
    fn init(
        self,
        geometry: &'a Geometry,
        env: &Environment,
        filter: &TransducerMask,
    ) -> Result<Self::G, GainError>;
}

#[doc(hidden)]
pub struct GainOperationGenerator<'a, G> {
    pub generator: G,
    pub segment: Segment,
    pub transition_params: TransitionModeParams,
    pub __phantom: core::marker::PhantomData<&'a ()>,
}

impl<'a, C: GainCalculatorGenerator<'a>> GainOperationGenerator<'a, C> {
    pub fn new<G: Gain<'a, G = C>>(
        gain: G,
        geometry: &'a Geometry,
        env: &Environment,
        filter: &DeviceMask,
        segment: Segment,
        transition_params: TransitionModeParams,
    ) -> Result<Self, GainError> {
        Ok(Self {
            generator: gain.init(geometry, env, &TransducerMask::from(filter))?,
            segment,
            transition_params,
            __phantom: core::marker::PhantomData,
        })
    }
}

#[derive(Debug, Clone, PartialEq)]
/// The result of the [`Gain`] inspection.
pub struct GainInspectionResult {
    /// The data of the gain.
    pub data: Vec<Drive>,
}