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 */ add(float value, long timeMs)31 void add(float value, long timeMs); 32 33 /** 34 * Alters the state of the filter such that it anticipates a change by the given amount. 35 * For example, if the filter is working with distance, and the distance of the next 36 * reading is expected to increase by 1 meter, 'shift' should be 1. 37 * @param shift How much to alter the filter state. 38 */ compensate(float shift)39 void compensate(float shift); 40 41 /** 42 * Gets a sample object with the result from the last computation. The sample's time is 43 * the average time of the samples that created the result, effectively describing the 44 * latency introduced by the filter. 45 * @return The result from the last computation. 46 */ 47 @NonNull getResult()48 Sample getResult(); 49 50 /** 51 * Gets a sample object with the result from the provided time. The returned sample's time is 52 * the closest the filter can provide to the given time. 53 * The default behavior is to return the latest available result, which is likely to be 54 * older than the requested time (see {@link #getResult()}). 55 * This must be overridden in order to support predicting filters like a Kalman filter or an 56 * extrapolating median/average filter. 57 * @param timeMs The preferred time of the predicted sample, in ms since boot. 58 * @return The result from the computation. 59 */ 60 @NonNull getResult(long timeMs)61 default Sample getResult(long timeMs) { 62 return getResult(); 63 } 64 } 65