1 /*
2  * Copyright (C) 2023 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package com.android.server.uwb.correction.filtering;
17 
18 import androidx.annotation.NonNull;
19 
20 /**
21  * Interface for a filter.
22  */
23 public interface IFilter {
24     /**
25      * Adds a value to the filter.
26      * @param value The value to add to the filter.
27      * @param timeMs When the value occurred, in ms since boot. Used to determine the latency
28      * introduced by the filter. Note that this has no effect on the order in which the filter
29      * operates on values.
30      * @param fom The figure of merit for the reading.
31      */
add(float value, long timeMs, double fom)32     void add(float value, long timeMs, double fom);
33 
34     /**
35      * Alters the state of the filter such that it anticipates a change by the given amount.
36      * For example, if the filter is working with distance, and the distance of the next
37      * reading is expected to increase by 1 meter, 'shift' should be 1.
38      * @param shift How much to alter the filter state.
39      */
compensate(float shift)40     void compensate(float shift);
41 
42     /**
43      * Gets a sample object with the result from the last computation. The sample's time is
44      * the average time of the samples that created the result, effectively describing the
45      * latency introduced by the filter.
46      * @return The result from the last computation.
47      */
48     @NonNull
getResult()49     Sample getResult();
50 
51     /**
52      * Gets a sample object with the result from the provided time. The returned sample's time is
53      * the closest the filter can provide to the given time.
54      * The default behavior is to return the latest available result, which is likely to be
55      * older than the requested time (see {@link #getResult()}).
56      * This must be overridden in order to support predicting filters like a Kalman filter or an
57      * extrapolating median/average filter.
58      * @param timeMs The preferred time of the predicted sample, in ms since boot.
59      * @return The result from the computation.
60      */
61     @NonNull
getResult(long timeMs)62     default Sample getResult(long timeMs) {
63         return getResult();
64     }
65 }
66