1 /* Copyright 2017 The TensorFlow Authors. All Rights Reserved. 2 3 Licensed under the Apache License, Version 2.0 (the "License"); 4 you may not use this file except in compliance with the License. 5 You may obtain a copy of the License at 6 7 http://www.apache.org/licenses/LICENSE-2.0 8 9 Unless required by applicable law or agreed to in writing, software 10 distributed under the License is distributed on an "AS IS" BASIS, 11 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 See the License for the specific language governing permissions and 13 limitations under the License. 14 ==============================================================================*/ 15 16 package org.tensorflow.lite; 17 18 import java.nio.ByteBuffer; 19 20 /** 21 * A typed multi-dimensional array used in Tensorflow Lite. 22 * 23 * <p>The native handle of a {@code Tensor} is managed by {@code NativeInterpreterWrapper}, and does 24 * not needed to be closed by the client. However, once the {@code NativeInterpreterWrapper} has 25 * been closed, the tensor handle will be invalidated. 26 */ 27 public interface Tensor { 28 29 /** 30 * Quantization parameters that corresponds to the table, {@code QuantizationParameters}, in the 31 * <a 32 * href="https://github.com/tensorflow/tensorflow/blob/master/tensorflow/lite/schema/schema.fbs">TFLite 33 * Model schema file.</a> 34 * 35 * <p>Since per-channel quantization does not apply to input and output tensors, {@code scale} and 36 * {@code zero_point} are both single values instead of arrays. 37 * 38 * <p>For tensor that are not quantized, the values of scale and zero_point are both 0. 39 * 40 * <p>Given a quantized value q, the corresponding float value f should be: <br> 41 * f = scale * (q - zero_point) <br> 42 */ 43 class QuantizationParams { 44 /** The scale value used in quantization. */ 45 private final float scale; 46 /** The zero point value used in quantization. */ 47 private final int zeroPoint; 48 49 /** 50 * Creates a {@link QuantizationParams} with {@code scale} and {@code zero_point}. 51 * 52 * @param scale The scale value used in quantization. 53 * @param zeroPoint The zero point value used in quantization. 54 */ QuantizationParams(final float scale, final int zeroPoint)55 public QuantizationParams(final float scale, final int zeroPoint) { 56 this.scale = scale; 57 this.zeroPoint = zeroPoint; 58 } 59 60 /** Returns the scale value. */ getScale()61 public float getScale() { 62 return scale; 63 } 64 65 /** Returns the zero point value. */ getZeroPoint()66 public int getZeroPoint() { 67 return zeroPoint; 68 } 69 } 70 71 /** Returns the {@link DataType} of elements stored in the Tensor. */ dataType()72 DataType dataType(); 73 74 /** 75 * Returns the number of dimensions (sometimes referred to as <a 76 * href="https://www.tensorflow.org/resources/dims_types.html#rank">rank</a>) of the Tensor. 77 * 78 * <p>Will be 0 for a scalar, 1 for a vector, 2 for a matrix, 3 for a 3-dimensional tensor etc. 79 */ numDimensions()80 int numDimensions(); 81 82 /** Returns the size, in bytes, of the tensor data. */ numBytes()83 int numBytes(); 84 85 /** Returns the number of elements in a flattened (1-D) view of the tensor. */ numElements()86 int numElements(); 87 88 /** 89 * Returns the <a href="https://www.tensorflow.org/resources/dims_types.html#shape">shape</a> of 90 * the Tensor, i.e., the sizes of each dimension. 91 * 92 * @return an array where the i-th element is the size of the i-th dimension of the tensor. 93 */ shape()94 int[] shape(); 95 96 /** 97 * Returns the original <a 98 * href="https://www.tensorflow.org/resources/dims_types.html#shape">shape</a> of the Tensor, 99 * i.e., the sizes of each dimension - before any resizing was performed. Unknown dimensions are 100 * designated with a value of -1. 101 * 102 * @return an array where the i-th element is the size of the i-th dimension of the tensor. 103 */ shapeSignature()104 int[] shapeSignature(); 105 106 /** 107 * Returns the (global) index of the tensor within the subgraph of the owning interpreter. 108 * 109 * @hide 110 */ index()111 int index(); 112 113 /** 114 * Returns the name of the tensor within the owning interpreter. 115 * 116 * @hide 117 */ name()118 String name(); 119 120 /** 121 * Returns the quantization parameters of the tensor within the owning interpreter. 122 * 123 * <p>Only quantized tensors have valid {@code QuantizationParameters}. For tensor that are not 124 * quantized, the values of scale and zero_point are both 0. 125 */ quantizationParams()126 QuantizationParams quantizationParams(); 127 128 /** 129 * Returns a read-only {@code ByteBuffer} view of the tensor data. 130 * 131 * <p>In general, this method is most useful for obtaining a read-only view of output tensor data, 132 * *after* inference has been executed (e.g., via {@link InterpreterApi#run(Object,Object)}). In 133 * particular, some graphs have dynamically shaped outputs, which can make feeding a predefined 134 * output buffer to the interpreter awkward. Example usage: 135 * 136 * <pre>{@code 137 * interpreter.run(input, null); 138 * ByteBuffer outputBuffer = interpreter.getOutputTensor(0).asReadOnlyBuffer(); 139 * // Copy or read from outputBuffer. 140 * }</pre> 141 * 142 * <p>WARNING: If the tensor has not yet been allocated, e.g., before inference has been executed, 143 * the result is undefined. Note that the underlying tensor pointer may also change when the 144 * tensor is invalidated in any way (e.g., if inference is executed, or the graph is resized), so 145 * it is *not* safe to hold a reference to the returned buffer beyond immediate use directly 146 * following inference. Example *bad* usage: 147 * 148 * <pre>{@code 149 * ByteBuffer outputBuffer = interpreter.getOutputTensor(0).asReadOnlyBuffer(); 150 * interpreter.run(input, null); 151 * // Copy or read from outputBuffer (which may now be invalid). 152 * }</pre> 153 * 154 * @throws IllegalArgumentException if the tensor data has not been allocated. 155 */ asReadOnlyBuffer()156 ByteBuffer asReadOnlyBuffer(); 157 } 158