tesseract v5.3.3.20231005
series.cpp
Go to the documentation of this file.
1
2// File: series.cpp
3// Description: Runs networks in series on the same input.
4// Author: Ray Smith
5//
6// (C) Copyright 2013, 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
18#include "series.h"
19
20#include "fullyconnected.h"
21#include "networkscratch.h"
22#include "scrollview.h"
23#include "tprintf.h"
24
25namespace tesseract {
26
27// ni_ and no_ will be set by AddToStack.
28Series::Series(const char *name) : Plumbing(name) {
30}
31
32// Returns the shape output from the network given an input shape (which may
33// be partially unknown ie zero).
34StaticShape Series::OutputShape(const StaticShape &input_shape) const {
35 StaticShape result(input_shape);
36 int stack_size = stack_.size();
37 for (int i = 0; i < stack_size; ++i) {
38 result = stack_[i]->OutputShape(result);
39 }
40 return result;
41}
42
43// Sets up the network for training. Initializes weights using weights of
44// scale `range` picked according to the random number generator `randomizer`.
45// Note that series has its own implementation just for debug purposes.
46int Series::InitWeights(float range, TRand *randomizer) {
47 num_weights_ = 0;
48 tprintf("Num outputs,weights in Series:\n");
49 for (auto &i : stack_) {
50 int weights = i->InitWeights(range, randomizer);
51 tprintf(" %s:%d, %d\n", i->spec().c_str(), i->NumOutputs(), weights);
52 num_weights_ += weights;
53 }
54 tprintf("Total weights = %d\n", num_weights_);
55 return num_weights_;
56}
57
58// Recursively searches the network for softmaxes with old_no outputs,
59// and remaps their outputs according to code_map. See network.h for details.
60int Series::RemapOutputs(int old_no, const std::vector<int> &code_map) {
61 num_weights_ = 0;
62 tprintf("Num (Extended) outputs,weights in Series:\n");
63 for (auto &i : stack_) {
64 int weights = i->RemapOutputs(old_no, code_map);
65 tprintf(" %s:%d, %d\n", i->spec().c_str(), i->NumOutputs(), weights);
66 num_weights_ += weights;
67 }
68 tprintf("Total weights = %d\n", num_weights_);
69 no_ = stack_.back()->NumOutputs();
70 return num_weights_;
71}
72
73// Sets needs_to_backprop_ to needs_backprop and returns true if
74// needs_backprop || any weights in this network so the next layer forward
75// can be told to produce backprop for this layer if needed.
76bool Series::SetupNeedsBackprop(bool needs_backprop) {
77 needs_to_backprop_ = needs_backprop;
78 for (auto &i : stack_) {
79 needs_backprop = i->SetupNeedsBackprop(needs_backprop);
80 }
81 return needs_backprop;
82}
83
84// Returns an integer reduction factor that the network applies to the
85// time sequence. Assumes that any 2-d is already eliminated. Used for
86// scaling bounding boxes of truth data.
87// WARNING: if GlobalMinimax is used to vary the scale, this will return
88// the last used scale factor. Call it before any forward, and it will return
89// the minimum scale factor of the paths through the GlobalMinimax.
91 int factor = 1;
92 for (auto i : stack_) {
93 factor *= i->XScaleFactor();
94 }
95 return factor;
96}
97
98// Provides the (minimum) x scale factor to the network (of interest only to
99// input units) so they can determine how to scale bounding boxes.
101 stack_[0]->CacheXScaleFactor(factor);
102}
103
104// Runs forward propagation of activations on the input line.
105// See NetworkCpp for a detailed discussion of the arguments.
106void Series::Forward(bool debug, const NetworkIO &input, const TransposedArray *input_transpose,
107 NetworkScratch *scratch, NetworkIO *output) {
108 int stack_size = stack_.size();
109 ASSERT_HOST(stack_size > 1);
110 // Revolving intermediate buffers.
111 NetworkScratch::IO buffer1(input, scratch);
112 NetworkScratch::IO buffer2(input, scratch);
113 // Run each network in turn, giving the output of n as the input to n + 1,
114 // with the final network providing the real output.
115 stack_[0]->Forward(debug, input, input_transpose, scratch, buffer1);
116 for (int i = 1; i < stack_size; i += 2) {
117 stack_[i]->Forward(debug, *buffer1, nullptr, scratch, i + 1 < stack_size ? buffer2 : output);
118 if (i + 1 == stack_size) {
119 return;
120 }
121 stack_[i + 1]->Forward(debug, *buffer2, nullptr, scratch,
122 i + 2 < stack_size ? buffer1 : output);
123 }
124}
125
126// Runs backward propagation of errors on the deltas line.
127// See NetworkCpp for a detailed discussion of the arguments.
128bool Series::Backward(bool debug, const NetworkIO &fwd_deltas, NetworkScratch *scratch,
129 NetworkIO *back_deltas) {
130 if (!IsTraining()) {
131 return false;
132 }
133 int stack_size = stack_.size();
134 ASSERT_HOST(stack_size > 1);
135 // Revolving intermediate buffers.
136 NetworkScratch::IO buffer1(fwd_deltas, scratch);
137 NetworkScratch::IO buffer2(fwd_deltas, scratch);
138 // Run each network in reverse order, giving the back_deltas output of n as
139 // the fwd_deltas input to n-1, with the 0 network providing the real output.
140 if (!stack_.back()->IsTraining() ||
141 !stack_.back()->Backward(debug, fwd_deltas, scratch, buffer1)) {
142 return false;
143 }
144 for (int i = stack_size - 2; i >= 0; i -= 2) {
145 if (!stack_[i]->IsTraining() ||
146 !stack_[i]->Backward(debug, *buffer1, scratch, i > 0 ? buffer2 : back_deltas)) {
147 return false;
148 }
149 if (i == 0) {
150 return needs_to_backprop_;
151 }
152 if (!stack_[i - 1]->IsTraining() ||
153 !stack_[i - 1]->Backward(debug, *buffer2, scratch, i > 1 ? buffer1 : back_deltas)) {
154 return false;
155 }
156 }
157 return needs_to_backprop_;
158}
159
160// Splits the series after the given index, returning the two parts and
161// deletes itself. The first part, up to network with index last_start, goes
162// into start, and the rest goes into end.
163void Series::SplitAt(unsigned last_start, Series **start, Series **end) {
164 *start = nullptr;
165 *end = nullptr;
166 if (last_start >= stack_.size()) {
167 tprintf("Invalid split index %u must be in range [0,%zu]!\n", last_start, stack_.size() - 1);
168 return;
169 }
170 auto *master_series = new Series("MasterSeries");
171 auto *boosted_series = new Series("BoostedSeries");
172 for (unsigned s = 0; s <= last_start; ++s) {
173 if (s + 1 == stack_.size() && stack_[s]->type() == NT_SOFTMAX) {
174 // Change the softmax to a tanh.
175 auto *fc = static_cast<FullyConnected *>(stack_[s]);
176 fc->ChangeType(NT_TANH);
177 }
178 master_series->AddToStack(stack_[s]);
179 stack_[s] = nullptr;
180 }
181 for (unsigned s = last_start + 1; s < stack_.size(); ++s) {
182 boosted_series->AddToStack(stack_[s]);
183 stack_[s] = nullptr;
184 }
185 *start = master_series;
186 *end = boosted_series;
187 delete this;
188}
189
190// Appends the elements of the src series to this, removing from src and
191// deleting it.
193 ASSERT_HOST(src->type() == NT_SERIES);
194 auto *src_series = static_cast<Series *>(src);
195 for (auto &s : src_series->stack_) {
196 AddToStack(s);
197 s = nullptr;
198 }
199 delete src;
200}
201
202} // namespace tesseract.
#define ASSERT_HOST(x)
Definition: errcode.h:54
void tprintf(const char *format,...)
Definition: tprintf.cpp:41
@ NT_SOFTMAX
Definition: network.h:66
@ NT_SERIES
Definition: network.h:52
@ NT_TANH
Definition: network.h:63
void ChangeType(NetworkType type)
NetworkType type_
Definition: network.h:300
bool needs_to_backprop_
Definition: network.h:302
bool IsTraining() const
Definition: network.h:113
int32_t num_weights_
Definition: network.h:306
NetworkType type() const
Definition: network.h:110
virtual void AddToStack(Network *network)
Definition: plumbing.cpp:84
std::vector< Network * > stack_
Definition: plumbing.h:147
bool SetupNeedsBackprop(bool needs_backprop) override
Definition: series.cpp:76
bool Backward(bool debug, const NetworkIO &fwd_deltas, NetworkScratch *scratch, NetworkIO *back_deltas) override
Definition: series.cpp:128
TESS_API void AppendSeries(Network *src)
Definition: series.cpp:192
TESS_API Series(const char *name)
Definition: series.cpp:28
int XScaleFactor() const override
Definition: series.cpp:90
TESS_API void SplitAt(unsigned last_start, Series **start, Series **end)
Definition: series.cpp:163
StaticShape OutputShape(const StaticShape &input_shape) const override
Definition: series.cpp:34
void CacheXScaleFactor(int factor) override
Definition: series.cpp:100
int InitWeights(float range, TRand *randomizer) override
Definition: series.cpp:46
int RemapOutputs(int old_no, const std::vector< int > &code_map) override
Definition: series.cpp:60
void Forward(bool debug, const NetworkIO &input, const TransposedArray *input_transpose, NetworkScratch *scratch, NetworkIO *output) override
Definition: series.cpp:106