tesseract  5.0.0-alpha-619-ge9db
stridemap.h
Go to the documentation of this file.
1 // File: stridemap.h
3 // Description: Indexing into a 4-d tensor held in a 2-d Array.
4 // Author: Ray Smith
5 //
6 // (C) Copyright 2016, Google Inc.
7 // Licensed under the Apache License, Version 2.0 (the "License");
8 // you may not use this file except in compliance with the License.
9 // You may obtain a copy of the License at
10 // http://www.apache.org/licenses/LICENSE-2.0
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
17 #ifndef TESSERACT_LSTM_STRIDEMAP_H_
18 #define TESSERACT_LSTM_STRIDEMAP_H_
19 
20 #include <cstring>
21 #include <vector>
22 
23 namespace tesseract {
24 
25 // Enum describing the dimensions of the 'Tensor' in a NetworkIO.
26 // A NetworkIO is analogous to a TF Tensor, except that the number of dimensions
27 // is fixed (4), and they always have the same meaning. The underlying
28 // representation is a 2-D array, for which the product batch*height*width
29 // is always dim1 and depth is always dim2. FlexDimensions is used only for
30 // batch, height, width with the StrideMap, and therefore represents the runtime
31 // shape. The build-time shape is defined by StaticShape.
33  FD_BATCH, // Index of multiple images.
34  FD_HEIGHT, // y-coordinate in image.
35  FD_WIDTH, // x-coordinate in image.
36  FD_DIMSIZE, // Number of flexible non-depth dimensions.
37 };
38 
39 // Encapsulation of information relating to the mapping from [batch][y][x] to
40 // the first index into the 2-d array underlying a NetworkIO.
41 class StrideMap {
42  public:
43  // Class holding the non-depth indices.
44  class Index {
45  public:
46  explicit Index(const StrideMap& stride_map) : stride_map_(&stride_map) {
47  InitToFirst();
48  }
49  Index(const StrideMap& stride_map, int batch, int y, int x)
50  : stride_map_(&stride_map) {
51  indices_[FD_BATCH] = batch;
52  indices_[FD_HEIGHT] = y;
53  indices_[FD_WIDTH] = x;
54  SetTFromIndices();
55  }
56  // Accesses the index to the underlying array.
57  int t() const { return t_; }
58  int index(FlexDimensions dimension) const { return indices_[dimension]; }
59  // Initializes the indices to the first valid location.
60  void InitToFirst() {
61  memset(indices_, 0, sizeof(indices_));
62  t_ = 0;
63  }
64  // Initializes the indices to the last valid location.
65  void InitToLast() { InitToLastOfBatch(MaxIndexOfDim(FD_BATCH)); }
66  // Returns true if *this is a valid index.
67  bool IsValid() const;
68  // Returns true if the index of the given dimension is the last.
69  bool IsLast(FlexDimensions dimension) const;
70  // Given that the dimensions up to and including dim-1 are valid, returns
71  // the maximum index for dimension dim.
72  int MaxIndexOfDim(FlexDimensions dim) const;
73  // Adds the given offset to the given dimension. Returns true if the result
74  // makes a valid index.
75  bool AddOffset(int offset, FlexDimensions dimension);
76  // Increments the index in some encapsulated way that guarantees to remain
77  // valid until it returns false, meaning that the iteration is complete.
78  bool Increment();
79  // Decrements the index in some encapsulated way that guarantees to remain
80  // valid until it returns false, meaning that the iteration (that started
81  // with InitToLast()) is complete.
82  bool Decrement();
83 
84  private:
85  // Initializes the indices to the last valid location in the given batch
86  // index.
87  void InitToLastOfBatch(int batch);
88  // Computes and sets t_ from the current indices_.
89  void SetTFromIndices();
90 
91  // Map into which *this is an index.
92  const StrideMap* stride_map_;
93  // Index to the first dimension of the underlying array.
94  int t_;
95  // Indices into the individual dimensions.
96  int indices_[FD_DIMSIZE];
97  };
98 
100  memset(shape_, 0, sizeof(shape_));
101  memset(t_increments_, 0, sizeof(t_increments_));
102  }
103  // Default copy constructor and operator= are OK to use here!
104 
105  // Sets up the stride for the given array of height, width pairs.
106  void SetStride(const std::vector<std::pair<int, int>>& h_w_pairs);
107  // Scales width and height dimensions by the given factors.
108  void ScaleXY(int x_factor, int y_factor);
109  // Reduces width to 1, across the batch, whatever the input size.
110  void ReduceWidthTo1();
111  // Transposes the width and height dimensions.
112  void TransposeXY();
113  // Returns the size of the given dimension.
114  int Size(FlexDimensions dimension) const { return shape_[dimension]; }
115  // Returns the total width required.
116  int Width() const { return t_increments_[FD_BATCH] * shape_[FD_BATCH]; }
117 
118  private:
119  // Computes t_increments_ from shape_.
120  void ComputeTIncrements();
121 
122  // The size of each non-depth dimension.
123  int shape_[FD_DIMSIZE];
124  // Precomputed 't' increments for each dimension. This is the value of
125  // the given dimension in the packed 3-d array that the shape_ represents.
126  int t_increments_[FD_DIMSIZE];
127  // Vector of size shape_[FD_BATCH] holds the height of each image in a batch.
128  std::vector<int> heights_;
129  // Vector of size shape_[FD_BATCH] holds the width of each image in a batch.
130  std::vector<int> widths_;
131 };
132 
133 } // namespace tesseract
134 
135 #endif // TESSERACT_LSTM_STRIDEMAP_H_
tesseract::StrideMap::StrideMap
StrideMap()
Definition: stridemap.h:99
tesseract::StrideMap::Size
int Size(FlexDimensions dimension) const
Definition: stridemap.h:114
tesseract::StrideMap::Index
Definition: stridemap.h:44
tesseract::StrideMap::Index::IsLast
bool IsLast(FlexDimensions dimension) const
Definition: stridemap.cpp:37
tesseract::StrideMap::ReduceWidthTo1
void ReduceWidthTo1()
Definition: stridemap.cpp:153
tesseract::StrideMap::Index::Index
Index(const StrideMap &stride_map, int batch, int y, int x)
Definition: stridemap.h:49
tesseract::FlexDimensions
FlexDimensions
Definition: stridemap.h:32
tesseract::StrideMap::Index::Index
Index(const StrideMap &stride_map)
Definition: stridemap.h:46
tesseract::StrideMap::Index::InitToLast
void InitToLast()
Definition: stridemap.h:65
tesseract::StrideMap::Index::index
int index(FlexDimensions dimension) const
Definition: stridemap.h:58
tesseract::StrideMap::Index::AddOffset
bool AddOffset(int offset, FlexDimensions dimension)
Definition: stridemap.cpp:62
tesseract::StrideMap::SetStride
void SetStride(const std::vector< std::pair< int, int >> &h_w_pairs)
Definition: stridemap.cpp:126
tesseract::StrideMap::Index::t
int t() const
Definition: stridemap.h:57
tesseract::FD_WIDTH
Definition: stridemap.h:35
tesseract::StrideMap::ScaleXY
void ScaleXY(int x_factor, int y_factor)
Definition: stridemap.cpp:144
tesseract
Definition: baseapi.h:65
tesseract::StrideMap::Index::MaxIndexOfDim
int MaxIndexOfDim(FlexDimensions dim) const
Definition: stridemap.cpp:43
tesseract::StrideMap::Index::InitToFirst
void InitToFirst()
Definition: stridemap.h:60
tesseract::FD_DIMSIZE
Definition: stridemap.h:36
tesseract::StrideMap::Index::Increment
bool Increment()
Definition: stridemap.cpp:70
tesseract::StrideMap
Definition: stridemap.h:41
tesseract::FD_HEIGHT
Definition: stridemap.h:34
tesseract::StrideMap::Width
int Width() const
Definition: stridemap.h:116
tesseract::StrideMap::Index::IsValid
bool IsValid() const
Definition: stridemap.cpp:24
tesseract::StrideMap::Index::Decrement
bool Decrement()
Definition: stridemap.cpp:87
tesseract::FD_BATCH
Definition: stridemap.h:33
tesseract::StrideMap::TransposeXY
void TransposeXY()
Definition: stridemap.cpp:160