Feat/roi align

docgen/src/main.rs

@@ -59,6 +59,14 @@ fn main() {
     doc_trait(trait_path, doc_path, label);
     doc_functions(trait_path, doc_path, trait_name, label);
 
+    // TREE ENSEMBLE DOC
+    let trait_path = "src/operators/ml/tree_ensemble/tree_ensemble.cairo";
+    let doc_path = "docs/framework/operators/machine-learning/tree-ensemble";
+    let label = "tree_ensemble";
+    let trait_name: &str = "TreeEnsembleTrait";
+    doc_trait(trait_path, doc_path, label);
+    doc_functions(trait_path, doc_path, trait_name, label);
+
     // LINEAR REGRESSOR DOC
     let trait_path = "src/operators/ml/linear/linear_regressor.cairo";
     let doc_path = "docs/framework/operators/machine-learning/linear-regressor";

docs/SUMMARY.md

@@ -178,6 +178,7 @@
     * [nn.conv](framework/operators/neural-network/nn.conv.md)
     * [nn.depth_to_space](framework/operators/neural-network/nn.depth_to_space.md)
     * [nn.space_to_depth](framework/operators/neural-network/nn.space_to_depth.md)
+    * [nn.roi\_align](framework/operators/neural-network/nn.roi\_align.md)
   * [Machine Learning](framework/operators/machine-learning/README.md)
     * [Tree Ensemble Classifier](framework/operators/machine-learning/tree-ensemble-classifier/README.md)
       * [tree\_ensemble\_classifier.predict](framework/operators/machine-learning/tree-ensemble-classifier/tree\_ensemble\_classifier.predict.md)

docs/framework/compatibility.md

@@ -47,6 +47,7 @@ You can see below the list of current supported ONNX Operators:
 |            [Col2im](operators/neural-network/nn.col2im\_sigmoid.md)           | :white\_check\_mark: |
 |       [ConvTranspose](operators/neural-network/nn.conv\_transpose_.md)        | :white\_check\_mark: |
 |                  [Conv](operators/neural-network/nn.conv.md)                  | :white\_check\_mark: |
+|             [RoiAlign](operators/neural-network/nn.roi\_align.md)             | :white\_check\_mark: |
 |                    [Sinh](operators/tensor/tensor.sinh.md)                    | :white\_check\_mark: |
 |                   [Asinh](operators/tensor/tensor.asinh.md)                   | :white\_check\_mark: |
 |                   [Atanh](operators/tensor/tensor.atanh.md)                   | :white\_check\_mark: |

docs/framework/operators/machine-learning/tree-ensemble/README.md

@@ -0,0 +1,22 @@
+# Tree Ensemble 
+
+`TreeEnsembleTrait` provides a trait definition for tree ensemble problem.
+
+```rust
+use orion::operators::ml::TreeEnsembleTrait;
+```
+
+### Data types
+
+Orion supports currently only fixed point data types for `TreeEnsembleTrait`.
+
+| Data type            | dtype                                                         |
+| -------------------- | ------------------------------------------------------------- |
+| Fixed point (signed) | `TreeEnsembleTrait<FP8x23 \| FP16x16 \| FP64x64 \| FP32x32>` |
+
+
+***
+
+| function | description |
+| --- | --- |
+| [`tree_ensemble.predict`](tree_ensemble.predict.md) | Returns the regressed values for each input in a batch. |

docs/framework/operators/machine-learning/tree-ensemble/tree_ensemble.predict.md

@@ -0,0 +1,139 @@
+# TreeEnsemble::predict
+
+```rust 
+   fn predict(X: @Tensor<T>,
+                  nodes_splits: Tensor<T>,
+                  nodes_featureids: Span<usize>,
+                  nodes_modes: Span<MODE>,
+                  nodes_truenodeids: Span<usize>,
+                  nodes_falsenodeids: Span<usize>,
+                  nodes_trueleafs: Span<usize>,
+                  nodes_falseleafs: Span<usize>,
+                  leaf_targetids: Span<usize>,
+                  leaf_weights: Tensor<T>,
+                  tree_roots: Span<usize>,
+                  post_transform: POST_TRANSFORM,
+                  aggregate_function: AGGREGATE_FUNCTION,
+                  nodes_hitrates: Option<Tensor<T>>,
+                  nodes_missing_value_tracks_true: Option<Span<usize>>,
+                  membership_values: Option<Tensor<T>>,
+                  n_targets: usize
+              ) -> MutMatrix::<T>;
+```
+
+Tree Ensemble operator. Returns the regressed values for each input in a batch. Inputs have dimensions [N, F] where N is the input batch size and F is the number of input features. Outputs have dimensions [N, num_targets] where N is the batch size and num_targets is the number of targets, which is a configurable attribute.
+
+## Args
+
+* `X`:  Input 2D tensor.
+* `nodes_splits`: Thresholds to do the splitting on for each node with mode that is not 'BRANCH_MEMBER'.
+* `nodes_featureids`: Feature id for each node.
+* `nodes_modes`: The comparison operation performed by the node. This is encoded as an enumeration of 'NODE_MODE::LEQ', 'NODE_MODE::LT', 'NODE_MODE::GTE', 'NODE_MODE::GT', 'NODE_MODE::EQ', 'NODE_MODE::NEQ', and 'NODE_MODE::MEMBER'
+* `nodes_truenodeids`: If `nodes_trueleafs` is 0 (false) at an entry, this represents the position of the true branch node. 
+* `nodes_falsenodeids`: If `nodes_falseleafs` is 0 (false) at an entry, this represents the position of the false branch node.
+* `nodes_trueleafs`: 1 if true branch is leaf for each node and 0 an interior node.
+* `nodes_falseleafs`: 1 if true branch is leaf for each node and 0 an interior node.
+* `leaf_targetids`: The index of the target that this leaf contributes to (this must be in range `[0, n_targets)`).
+* `leaf_weights`: The weight for each leaf.
+* `tree_roots`: Index into `nodes_*` for the root of each tree. The tree structure is derived from the branching of each node.
+* `post_transform`: Indicates the transform to apply to the score.One of 'POST_TRANSFORM::NONE', 'POST_TRANSFORM::SOFTMAX', 'POST_TRANSFORM::LOGISTIC', 'POST_TRANSFORM::SOFTMAX_ZERO'  or 'POST_TRANSFORM::PROBIT' ,
+* `aggregate_function`: Defines how to aggregate leaf values within a target. One of 'AGGREGATE_FUNCTION::AVERAGE', 'AGGREGATE_FUNCTION::SUM', 'AGGREGATE_FUNCTION::MIN', 'AGGREGATE_FUNCTION::MAX` defaults to 'AGGREGATE_FUNCTION::SUM' 
+* `nodes_hitrates`: Popularity of each node, used for performance and may be omitted.
+* `nodes_missing_value_tracks_true`: For each node, define whether to follow the true branch (if attribute value is 1) or false branch (if attribute value is 0) in the presence of a NaN input feature. This attribute may be left undefined and the default value is false (0) for all nodes.
+* `membership_values`: Members to test membership of for each set membership node. List all of the members to test again in the order that the 'BRANCH_MEMBER' mode appears in `node_modes`, delimited by `NaN`s. Will have the same number of sets of values as nodes with mode 'BRANCH_MEMBER'. This may be omitted if the node doesn't contain any 'BRANCH_MEMBER' nodes.
+* `n_targets`: The total number of targets.
+
+
+## Returns
+
+* Output of shape [Batch Size, Number of targets]
+
+## Type Constraints
+
+`TreeEnsembleClassifier` and `X` must be fixed points
+
+## Examples
+
+```rust
+use orion::numbers::FP16x16;
+use orion::operators::tensor::{Tensor, TensorTrait, FP16x16Tensor, U32Tensor};
+use orion::operators::ml::{TreeEnsembleTrait,POST_TRANSFORM, AGGREGATE_FUNCTION, NODE_MODE};
+use orion::operators::matrix::{MutMatrix, MutMatrixImpl};
+use orion::numbers::NumberTrait;
+
+fn example_tree_ensemble_one_tree() ->  MutMatrix::<FP16x16> {
+    let mut shape = ArrayTrait::<usize>::new();
+    shape.append(3);
+    shape.append(2);
+
+    let mut data = ArrayTrait::new();
+    data.append(FP16x16 { mag: 78643, sign: false });
+    data.append(FP16x16 { mag: 222822, sign: false });
+    data.append(FP16x16 { mag: 7864, sign: true });
+    data.append(FP16x16 { mag: 108789, sign: false });
+    data.append(FP16x16 { mag: 271319, sign: false });
+    data.append(FP16x16 { mag: 115998, sign: false });
+    let mut X = TensorTrait::new(shape.span(), data.span());
+
+    let mut shape = ArrayTrait::<usize>::new();
+    shape.append(4);
+
+    let mut data = ArrayTrait::new();
+    data.append(FP16x16 { mag: 342753, sign: false });
+    data.append(FP16x16 { mag: 794296, sign: false });
+    data.append(FP16x16 { mag: 801505, sign: true });
+    data.append(FP16x16 { mag: 472514, sign: false });
+    let leaf_weights = TensorTrait::new(shape.span(), data.span());
+
+    let mut shape = ArrayTrait::<usize>::new();
+    shape.append(3);
+
+    let mut data = ArrayTrait::new();
+    data.append(FP16x16 { mag: 205783, sign: false });
+    data.append(FP16x16 { mag: 78643, sign: false });
+    data.append(FP16x16 { mag: 275251, sign: false });
+    let nodes_splits = TensorTrait::new(shape.span(), data.span());
+
+    let membership_values = Option::None;
+
+    let n_targets = 2;
+    let aggregate_function = AGGREGATE_FUNCTION::SUM;
+    let nodes_missing_value_tracks_true = Option::None;
+    let nodes_hitrates = Option::None;
+    let post_transform = POST_TRANSFORM::NONE;
+
+    let tree_roots: Span<usize> = array![0].span();
+    let nodes_modes: Span<MODE> = array![MODE::LEQ, MODE::LEQ, MODE::LEQ].span();
+
+    let nodes_featureids: Span<usize> = array![0, 0, 0].span();
+    let nodes_truenodeids: Span<usize> = array![1, 0, 1].span();
+    let nodes_trueleafs: Span<usize> = array![0, 1, 1].span();
+    let nodes_falsenodeids: Span<usize> = array![2, 2, 3].span();
+    let nodes_falseleafs: Span<usize> = array![0, 1, 1].span();
+    let leaf_targetids: Span<usize> = array![0, 1, 0, 1].span();
+
+    return TreeEnsembleTrait::predict(
+        @X,
+        nodes_splits,
+        nodes_featureids,
+        nodes_modes,
+        nodes_truenodeids,
+        nodes_falsenodeids,
+        nodes_trueleafs,
+        nodes_falseleafs,
+        leaf_targetids,
+        leaf_weights,
+        tree_roots,
+        post_transform,
+        aggregate_function,
+        nodes_hitrates,
+        nodes_missing_value_tracks_true,
+        membership_values,
+        n_targets
+    );
+}
+
+>>> [[ 5.23  0.  ]
+     [ 5.23  0.  ]
+     [ 0.   12.12]]    
+```

docs/framework/operators/neural-network/nn.roi_align.md

@@ -0,0 +1,126 @@
+# NNTrait::roi_align
+
+```rust
+    fn roi_align(
+    X: @Tensor<T>,
+    roi: @Tensor<T>,
+    batch_indices: @Tensor<usize>,
+    coordinate_transformation_mode: Option<
+        orion::operators::nn::functional::roi_align::TRANSFORMATION_MODE
+    >,
+    mode: Option<orion::operators::nn::functional::roi_align::MODE>,
+    output_height: Option<usize>,
+    output_width: Option<usize>,
+    sampling_ratio: Option<T>,
+    spatial_scale: Option<T>,
+) -> Tensor<T>;
+```
+
+ RoiAlign consumes an input tensor X and region of interests (rois) to apply pooling across each RoI; it produces a 4-D tensor of shape (num_rois, C, output_height, output_width).
+
+## Args
+
+* `X`(`@Tensor<T>`) - Input data tensor from the previous operator; 4-D feature map of shape (N, C, H, W), where N is the batch size, C is the number of channels, and H and W are the height and the width of the data.
+* `rois`(`@Tensor<T>`) - RoIs (Regions of Interest) to pool over; rois is 2-D input of shape (num_rois, 4) given as [[x1, y1, x2, y2], ...].
+* `batch_indices`(`@Tensor<usize>`) - 1-D tensor of shape (num_rois,) with each element denoting the index of the corresponding image in the batch.
+* `coordinate_transformation_mode`(`Option<TRANSFORMATION_MODE>`) - Allowed values are 'half_pixel' and 'output_half_pixel'. Use the value 'half_pixel' to pixel shift the input coordinates by -0.5 (default behavior). Use the value 'output_half_pixel' to omit the pixel shift for the input
+* `mode`(`Option<MODE>`) -The pooling method. Two modes are supported: 'avg' and 'max'. Default is 'avg'.
+* `output_height`(`Option<usize>`) - default 1; Pooled output Y's height.
+* `output_width`(`Option<usize>`) - default 1; Pooled output Y's width.
+* `sampling_ratio`(`Option<T>`) - Number of sampling points in the interpolation grid used to compute the output value of each pooled output bin. If > 0, then exactly sampling_ratio x sampling_ratio grid points are used. If == 0, then an adaptive number of grid points are used (computed as ceil(roi_width / output_width), and likewise for height). Default is 0.
+* `spatial_scale`(`Option<T>`) - Multiplicative spatial scale factor to translate ROI coordinates from their input spatial scale to the scale used when pooling, i.e., spatial scale of the input feature map X relative to the input image. Default is 1.0. 
+
+## Returns
+
+A `Tensor<T>` RoI pooled output, 4-D tensor of shape (num_rois, C, output_height, output_width). The r-th batch element Y[r-1] is a pooled feature map corresponding to the r-th RoI X[r-1].
+
+## Example
+
+```rust
+use orion::operators::nn::NNTrait;
+use orion::numbers::FixedTrait;
+use orion::operators::nn::FP16x16NN;
+use orion::numbers::FP16x16;
+use orion::operators::tensor::{Tensor, TensorTrait, FP16x16Tensor};
+use orion::operators::nn::functional::roi_align::TRANSFORMATION_MODE;
+
+fn example_roi_align() -> Tensor<FP16x16> {
+    let mut shape = ArrayTrait::<usize>::new();
+    shape.append(1);
+    shape.append(1);
+    shape.append(5);
+    shape.append(5);
+
+    let mut data = ArrayTrait::new();
+    data.append(FP16x16 { mag: 18114, sign: false });
+    data.append(FP16x16 { mag: 46858, sign: false });
+    data.append(FP16x16 { mag: 12831, sign: false });
+    data.append(FP16x16 { mag: 22387, sign: false });
+    data.append(FP16x16 { mag: 30395, sign: false });
+    data.append(FP16x16 { mag: 63157, sign: false });
+    data.append(FP16x16 { mag: 5865, sign: false });
+    data.append(FP16x16 { mag: 19129, sign: false });
+    data.append(FP16x16 { mag: 44256, sign: false });
+    data.append(FP16x16 { mag: 1533, sign: false });
+    data.append(FP16x16 { mag: 21397, sign: false });
+    data.append(FP16x16 { mag: 55567, sign: false });
+    data.append(FP16x16 { mag: 63556, sign: false });
+    data.append(FP16x16 { mag: 16193, sign: false });
+    data.append(FP16x16 { mag: 61184, sign: false });
+    data.append(FP16x16 { mag: 1350, sign: false });
+    data.append(FP16x16 { mag: 11272, sign: false });
+    data.append(FP16x16 { mag: 14123, sign: false });
+    data.append(FP16x16 { mag: 28796, sign: false });
+    data.append(FP16x16 { mag: 4279, sign: false });
+    data.append(FP16x16 { mag: 26620, sign: false });
+    data.append(FP16x16 { mag: 14378, sign: false });
+    data.append(FP16x16 { mag: 29314, sign: false });
+    data.append(FP16x16 { mag: 30716, sign: false });
+    data.append(FP16x16 { mag: 46589, sign: false });
+    let mut X = TensorTrait::new(shape.span(), data.span());
+
+    let batch_indices = TensorTrait::new(array![3].span(), array![0, 0, 0].span());
+
+    let mut shape = ArrayTrait::<usize>::new();
+    shape.append(3);
+    shape.append(4);
+
+    let mut data = ArrayTrait::new();
+    data.append(FP16x16 { mag: 0, sign: false });
+    data.append(FP16x16 { mag: 0, sign: false });
+    data.append(FP16x16 { mag: 589824, sign: false });
+    data.append(FP16x16 { mag: 589824, sign: false });
+    data.append(FP16x16 { mag: 0, sign: false });
+    data.append(FP16x16 { mag: 327680, sign: false });
+    data.append(FP16x16 { mag: 262144, sign: false });
+    data.append(FP16x16 { mag: 589824, sign: false });
+    data.append(FP16x16 { mag: 327680, sign: false });
+    data.append(FP16x16 { mag: 327680, sign: false });
+    data.append(FP16x16 { mag: 589824, sign: false });
+    data.append(FP16x16 { mag: 589824, sign: false });
+    let rois = TensorTrait::new(shape.span(), data.span());
+
+    return roi_align(
+        @X,
+        @rois,
+        @batch_indices,
+        Option::Some(TRANSFORMATION_MODE::OUTPUT_HALF_PIXEL),
+        Option::None,
+        Option::Some(2),
+        Option::Some(2),
+        Option::Some(FP16x16 { mag: 65536, sign: false }),
+        Option::Some(FP16x16 { mag: 32768, sign: false }),
+    );
+}
+>>> [[[[0.2083422 , 0.44005   ],
+        [0.20385626, 0.39676717]]],
+
+
+      [[[0.09630001, 0.19375   ],
+        [0.3128    , 0.33335   ]]],
+
+
+      [[[0.4394    , 0.0653    ],
+        [0.4687    , 0.7109    ]]]]
+
+````