2 * Copyright (c) 2017-2018 ARM Limited.
4 * SPDX-License-Identifier: MIT
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to
8 * deal in the Software without restriction, including without limitation the
9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10 * sell copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
13 * The above copyright notice and this permission notice shall be included in all
14 * copies or substantial portions of the Software.
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
24 #ifndef __ARM_COMPUTE_GRAPH_UTILS_H__
25 #define __ARM_COMPUTE_GRAPH_UTILS_H__
27 #include "arm_compute/core/PixelValue.h"
28 #include "arm_compute/core/utils/misc/Utility.h"
29 #include "arm_compute/graph/Graph.h"
30 #include "arm_compute/graph/ITensorAccessor.h"
31 #include "arm_compute/graph/Types.h"
32 #include "arm_compute/runtime/Tensor.h"
43 /** Preprocessor interface **/
47 /** Default destructor. */
48 virtual ~IPreprocessor() = default;
49 /** Preprocess the given tensor.
51 * @param[in] tensor Tensor to preprocess.
53 virtual void preprocess(ITensor &tensor) = 0;
56 /** Caffe preproccessor */
57 class CaffePreproccessor : public IPreprocessor
60 /** Default Constructor
62 * @param mean Mean array in RGB ordering
63 * @param bgr Boolean specifying if the preprocessing should assume BGR format
65 CaffePreproccessor(std::array<float, 3> mean = std::array<float, 3> { { 0, 0, 0 } }, bool bgr = true);
66 void preprocess(ITensor &tensor) override;
69 std::array<float, 3> _mean;
73 /** TF preproccessor */
74 class TFPreproccessor : public IPreprocessor
77 void preprocess(ITensor &tensor) override;
80 /** PPM writer class */
81 class PPMWriter : public graph::ITensorAccessor
86 * @param[in] name PPM file name
87 * @param[in] maximum Maximum elements to access
89 PPMWriter(std::string name, unsigned int maximum = 1);
90 /** Allows instances to move constructed */
91 PPMWriter(PPMWriter &&) = default;
93 // Inherited methods overriden:
94 bool access_tensor(ITensor &tensor) override;
97 const std::string _name;
98 unsigned int _iterator;
99 unsigned int _maximum;
102 /** Dummy accessor class */
103 class DummyAccessor final : public graph::ITensorAccessor
108 * @param[in] maximum Maximum elements to write
110 DummyAccessor(unsigned int maximum = 1);
111 /** Allows instances to move constructed */
112 DummyAccessor(DummyAccessor &&) = default;
114 // Inherited methods overriden:
115 bool access_tensor(ITensor &tensor) override;
118 unsigned int _iterator;
119 unsigned int _maximum;
122 /** NumPy accessor class */
123 class NumPyAccessor final : public graph::ITensorAccessor
128 * @param[in] npy_path Path to npy file.
129 * @param[in] shape Shape of the numpy tensor data.
130 * @param[in] data_type DataType of the numpy tensor data.
131 * @param[out] output_stream (Optional) Output stream
133 NumPyAccessor(std::string npy_path, TensorShape shape, DataType data_type, std::ostream &output_stream = std::cout);
134 /** Allow instances of this class to be move constructed */
135 NumPyAccessor(NumPyAccessor &&) = default;
136 /** Prevent instances of this class from being copied (As this class contains pointers) */
137 NumPyAccessor(const NumPyAccessor &) = delete;
138 /** Prevent instances of this class from being copied (As this class contains pointers) */
139 NumPyAccessor &operator=(const NumPyAccessor &) = delete;
141 // Inherited methods overriden:
142 bool access_tensor(ITensor &tensor) override;
145 template <typename T>
146 void access_numpy_tensor(ITensor &tensor);
149 const std::string _filename;
150 std::ostream &_output_stream;
153 /** PPM accessor class */
154 class PPMAccessor final : public graph::ITensorAccessor
159 * @param[in] ppm_path Path to PPM file
160 * @param[in] bgr (Optional) Fill the first plane with blue channel (default = false)
161 * @param[in] preprocessor (Optional) PPM pre-processing object
163 PPMAccessor(std::string ppm_path, bool bgr = true, std::unique_ptr<IPreprocessor> preprocessor = nullptr);
164 /** Allow instances of this class to be move constructed */
165 PPMAccessor(PPMAccessor &&) = default;
167 // Inherited methods overriden:
168 bool access_tensor(ITensor &tensor) override;
171 const std::string _ppm_path;
173 std::unique_ptr<IPreprocessor> _preprocessor;
176 /** Result accessor class */
177 class TopNPredictionsAccessor final : public graph::ITensorAccessor
182 * @param[in] labels_path Path to labels text file.
183 * @param[in] top_n (Optional) Number of output classes to print
184 * @param[out] output_stream (Optional) Output stream
186 TopNPredictionsAccessor(const std::string &labels_path, size_t top_n = 5, std::ostream &output_stream = std::cout);
187 /** Allow instances of this class to be move constructed */
188 TopNPredictionsAccessor(TopNPredictionsAccessor &&) = default;
189 /** Prevent instances of this class from being copied (As this class contains pointers) */
190 TopNPredictionsAccessor(const TopNPredictionsAccessor &) = delete;
191 /** Prevent instances of this class from being copied (As this class contains pointers) */
192 TopNPredictionsAccessor &operator=(const TopNPredictionsAccessor &) = delete;
194 // Inherited methods overriden:
195 bool access_tensor(ITensor &tensor) override;
198 template <typename T>
199 void access_predictions_tensor(ITensor &tensor);
201 std::vector<std::string> _labels;
202 std::ostream &_output_stream;
206 /** Random accessor class */
207 class RandomAccessor final : public graph::ITensorAccessor
212 * @param[in] lower Lower bound value.
213 * @param[in] upper Upper bound value.
214 * @param[in] seed (Optional) Seed used to initialise the random number generator.
216 RandomAccessor(PixelValue lower, PixelValue upper, const std::random_device::result_type seed = 0);
217 /** Allows instances to move constructed */
218 RandomAccessor(RandomAccessor &&) = default;
220 // Inherited methods overriden:
221 bool access_tensor(ITensor &tensor) override;
224 template <typename T, typename D>
225 void fill(ITensor &tensor, D &&distribution);
228 std::random_device::result_type _seed;
231 /** Numpy Binary loader class*/
232 class NumPyBinLoader final : public graph::ITensorAccessor
235 /** Default Constructor
237 * @param[in] filename Binary file name
238 * @param[in] file_layout (Optional) Layout of the numpy tensor data. Defaults to NCHW
240 NumPyBinLoader(std::string filename, DataLayout file_layout = DataLayout::NCHW);
241 /** Allows instances to move constructed */
242 NumPyBinLoader(NumPyBinLoader &&) = default;
244 // Inherited methods overriden:
245 bool access_tensor(ITensor &tensor) override;
248 const std::string _filename;
249 const DataLayout _file_layout;
252 /** Generates appropriate random accessor
254 * @param[in] lower Lower random values bound
255 * @param[in] upper Upper random values bound
256 * @param[in] seed Random generator seed
258 * @return A ramdom accessor
260 inline std::unique_ptr<graph::ITensorAccessor> get_random_accessor(PixelValue lower, PixelValue upper, const std::random_device::result_type seed = 0)
262 return arm_compute::support::cpp14::make_unique<RandomAccessor>(lower, upper, seed);
265 /** Generates appropriate weights accessor according to the specified path
267 * @note If path is empty will generate a DummyAccessor else will generate a NumPyBinLoader
269 * @param[in] path Path to the data files
270 * @param[in] data_file Relative path to the data files from path
271 * @param[in] file_layout (Optional) Layout of file. Defaults to NCHW
273 * @return An appropriate tensor accessor
275 inline std::unique_ptr<graph::ITensorAccessor> get_weights_accessor(const std::string &path,
276 const std::string &data_file,
277 DataLayout file_layout = DataLayout::NCHW)
281 return arm_compute::support::cpp14::make_unique<DummyAccessor>();
285 return arm_compute::support::cpp14::make_unique<NumPyBinLoader>(path + data_file, file_layout);
289 /** Generates appropriate input accessor according to the specified ppm_path
291 * @note If ppm_path is empty will generate a DummyAccessor else will generate a PPMAccessor
293 * @param[in] ppm_path Path to PPM file
294 * @param[in] preprocessor Preproccessor object
295 * @param[in] bgr (Optional) Fill the first plane with blue channel (default = true)
297 * @return An appropriate tensor accessor
299 inline std::unique_ptr<graph::ITensorAccessor> get_input_accessor(const std::string &ppm_path,
300 std::unique_ptr<IPreprocessor> preprocessor = nullptr,
305 return arm_compute::support::cpp14::make_unique<DummyAccessor>();
309 if(arm_compute::utility::endswith(ppm_path, ".npy"))
311 return arm_compute::support::cpp14::make_unique<NumPyBinLoader>(ppm_path);
315 return arm_compute::support::cpp14::make_unique<PPMAccessor>(ppm_path, bgr, std::move(preprocessor));
320 /** Generates appropriate output accessor according to the specified labels_path
322 * @note If labels_path is empty will generate a DummyAccessor else will generate a TopNPredictionsAccessor
324 * @param[in] labels_path Path to labels text file
325 * @param[in] top_n (Optional) Number of output classes to print
326 * @param[out] output_stream (Optional) Output stream
328 * @return An appropriate tensor accessor
330 inline std::unique_ptr<graph::ITensorAccessor> get_output_accessor(const std::string &labels_path, size_t top_n = 5, std::ostream &output_stream = std::cout)
332 if(labels_path.empty())
334 return arm_compute::support::cpp14::make_unique<DummyAccessor>(0);
338 return arm_compute::support::cpp14::make_unique<TopNPredictionsAccessor>(labels_path, top_n, output_stream);
341 /** Generates appropriate npy output accessor according to the specified npy_path
343 * @note If npy_path is empty will generate a DummyAccessor else will generate a NpyAccessor
345 * @param[in] npy_path Path to npy file.
346 * @param[in] shape Shape of the numpy tensor data.
347 * @param[in] data_type DataType of the numpy tensor data.
348 * @param[out] output_stream (Optional) Output stream
350 * @return An appropriate tensor accessor
352 inline std::unique_ptr<graph::ITensorAccessor> get_npy_output_accessor(const std::string &npy_path, TensorShape shape, DataType data_type, std::ostream &output_stream = std::cout)
356 return arm_compute::support::cpp14::make_unique<DummyAccessor>(0);
360 return arm_compute::support::cpp14::make_unique<NumPyAccessor>(npy_path, shape, data_type, output_stream);
364 /** Utility function to return the TargetHint
366 * @param[in] target Integer value which expresses the selected target. Must be 0 for NEON or 1 for OpenCL or 2 (OpenCL with Tuner)
368 * @return the TargetHint
370 inline graph::Target set_target_hint(int target)
372 ARM_COMPUTE_ERROR_ON_MSG(target > 3, "Invalid target. Target must be 0 (NEON), 1 (OpenCL), 2 (OpenCL + Tuner), 3 (GLES)");
373 if((target == 1 || target == 2))
375 return graph::Target::CL;
379 return graph::Target::GC;
383 return graph::Target::NEON;
386 } // namespace graph_utils
387 } // namespace arm_compute
389 #endif /* __ARM_COMPUTE_GRAPH_UTILS_H__ */