Ocean
Loading...
Searching...
No Matches
Constraint.h
Go to the documentation of this file.
1/*
2 * Copyright (c) Meta Platforms, Inc. and affiliates.
3 *
4 * This source code is licensed under the MIT license found in the
5 * LICENSE file in the root directory of this source tree.
6 */
7
8#ifndef META_OCEAN_CV_SYNTHESIS_CONSTRAINT_H
9#define META_OCEAN_CV_SYNTHESIS_CONSTRAINT_H
10
12
13#include "ocean/base/Frame.h"
14
15#include "ocean/math/Vector2.h"
16#include "ocean/math/Vector3.h"
17
18namespace Ocean
19{
20
21namespace CV
22{
23
24namespace Synthesis
25{
26
27/**
28 * This class is the base class for all constraints.
29 * Constraints can be used to improve the image quality of a synthesized image.<br>
30 * Constraints cover e.g., geometrical structures, patterns or other kinds of visual information not entirely converted by a patch-based synthesis.
31 * @ingroup cvsynthesis
32 */
33class OCEAN_CV_SYNTHESIS_EXPORT Constraint
34{
35 friend class Constraints;
36
37 public:
38
39 /**
40 * Destructs this constraint.
41 */
42 virtual ~Constraint() = default;
43
44 /**
45 * Creates an empty constraint.
46 * @param impact The impact factor, with range [0, infinity)
47 */
48 inline explicit Constraint(const Scalar impact);
49
50 /**
51 * Returns the impact factor of this constraint.
52 * @return Constraint impact factor
53 */
54 inline Scalar impact() const;
55
56 /**
57 * Returns the cost for a given for two given points.
58 * @param inside The inside point (point inside the mask to determine the cost for - according to the second point)
59 * @param outside The outside point (point outside the mask)
60 * @return Constraint cost
61 */
62 virtual Scalar cost(const Vector2& inside, const Vector2& outside) const = 0;
63
64 /**
65 * Returns the weight of this constraint according to a given point.
66 * @param point The point to determine the weight for
67 * @return Resulting weight
68 */
69 virtual Scalar weight(const Vector2& point) const = 0;
70
71 protected:
72
73 /**
74 * Creates an empty constraint.
75 */
76 Constraint() = default;
77
78 /**
79 * Creates a copy of this constraint by an optional scale parameter.
80 * A scale of 0.5 provide a constraint for an image with bisected dimensions.<br>
81 * The resulting object has to be released by the caller.<br>
82 * @param scale The scale to be used
83 */
84 virtual std::unique_ptr<Constraint> copy(const Scalar scale = Scalar(1)) const = 0;
85
86 protected:
87
88 /// Impact factor of this constraint.
90};
91
92/**
93 * This class implements a structure constraint.
94 * @ingroup cvsynthesis
95 */
96class OCEAN_CV_SYNTHESIS_EXPORT StructureConstraint : public Constraint
97{
98 public:
99
100 /**
101 * Creates a new structure constraint object.
102 * @param impact The impact factor, with range [0, infinity)
103 * @param radius Impact radius of this constraint, with range (0, infinity)
104 */
105 inline explicit StructureConstraint(const Scalar impact, const Scalar radius);
106
107 /**
108 * Returns the radius of this constraint.
109 * @return Impact radius
110 */
111 inline Scalar radius() const;
112
113 /**
114 * Returns the weight of this constraint according to a given point.
115 * @param point The point to determine the weight for
116 * @return Resulting weight
117 */
118 virtual Scalar weight(const Vector2& point) const = 0;
119
120 protected:
121
122 /// Impact radius of this structure constraint.
124
125 /// Radius parameter of this constraint: 1 / (1/4 * radius)
127};
128
129/**
130 * This class implement a line constraint.
131 * @ingroup cvsynthesis
132 */
133class OCEAN_CV_SYNTHESIS_EXPORT LineConstraint : public StructureConstraint
134{
135 public:
136
137 /**
138 * Creates a new line constraint object for infinite lines.
139 * @param point0 First point of the infinite line
140 * @param point1 Second point of the infinite line
141 * @param impact The impact factor, with range [0, infinity)
142 * @param radius Impact radius of this constraint, with range (0, infinity)
143 */
144 inline LineConstraint(const Vector2& point0, const Vector2& point1, const Scalar impact, const Scalar radius);
145
146 /**
147 * Creates a new finite line constraint object by an already defined one.
148 * @param constraint Finite line constraint
149 * @param scale The scale factor to be applied
150 */
151 inline LineConstraint(const LineConstraint& constraint, const Scalar scale);
152
153 /**
154 * Returns the first point of this line.
155 * @return First point
156 */
157 inline const Vector2& point0() const;
158
159 /**
160 * Returns the second point of this line.
161 * @return First point
162 */
163 inline const Vector2& point1() const;
164
165 /**
166 * Returns the weight of this constraint according to a given point.
167 * @see StructureConstraint::weight().
168 */
169 Scalar weight(const Vector2& point) const override;
170
171 /**
172 * Returns the cost for a given for two given points.
173 * @see Constraint::cost().
174 */
175 Scalar cost(const Vector2& inside, const Vector2& outside) const override;
176
177 /**
178 * Returns the distance between a given point and this infinite line.
179 * @param point The point to determine the distance for
180 * @return Resulting distance
181 */
182 inline Scalar infiniteLineDistance(const Vector2& point) const;
183
184 /**
185 * Returns the weight of this constraint according to a given distance.
186 * @param distance Already determined distance of an arbitrary point
187 * @return Determined weight
188 */
189 inline Scalar weight(const Scalar distance) const;
190
191 protected:
192
193 /**
194 * Creates a copy of this constraint by an optional scale parameter.
195 * @see Constraint::copy().
196 */
197 std::unique_ptr<Constraint> copy(const Scalar scale = 1) const override;
198
199 protected:
200
201 /// First point of the line.
203
204 /// Second point of the line.
206
207 /// Normal (x, y) and distance (z) of the line.
209};
210
211/**
212 * This class implements a finite line constraint.
213 * @ingroup cvsynthesis
214 */
215class OCEAN_CV_SYNTHESIS_EXPORT FiniteLineConstraint : public LineConstraint
216{
217 public:
218
219 /**
220 * Creates a new finite line constraint object.
221 * @param point0 First point of the infinite line
222 * @param point1 Second point of the infinite line
223 * @param impact The impact factor, with range [0, infinity)
224 * @param radius Impact radius of this constraint, with range (0, infinity)
225 * @param penalty The penalty value if the point is outside the finite line
226 * @param finite0 State to finite the line at the first point
227 * @param finite1 State to finite the line at the second point
228 */
229 inline FiniteLineConstraint(const Vector2& point0, const Vector2& point1, const Scalar impact, const Scalar radius, const Scalar penalty, const bool finite0, const bool finite1);
230
231 /**
232 * Creates a new finite line constraint object by an already defined one.
233 * @param constraint Finite line constraint
234 * @param scale The scale factor to be applied
235 */
236 inline FiniteLineConstraint(const FiniteLineConstraint& constraint, const Scalar scale);
237
238 /**
239 * Returns the penalty factor of this line constraint.
240 * @return Penalty factor
241 */
242 inline Scalar penalty() const;
243
244 /**
245 * Returns the finite state of the first point.
246 * @return True, if the line is finite at the first point
247 */
248 inline bool finite0() const;
249
250 /**
251 * Returns the finite state of the second point.
252 * @return True, if the line is finite at the second point
253 */
254 inline bool finite1() const;
255
256 /**
257 * Returns the weight of this constraint according to a given point.
258 * @see StructureConstraint::weight().
259 */
260 Scalar weight(const Vector2& point) const override;
261
262 /**
263 * Returns the cost for a given for two given points.
264 * @see Constraint::cost().
265 */
266 Scalar cost(const Vector2& inside, const Vector2& outside) const override;
267
268 /**
269 * Returns the distance between a given point and this infinite line.
270 * @param point The point to determine the distance for
271 * @return Resulting distance
272 */
273 inline Scalar finiteLineDistance(const Vector2& point) const;
274
275 /**
276 * Creates a copy of this constraint by an optional scale parameter.
277 * @see Constraint::copy().
278 */
279 std::unique_ptr<Constraint> copy(const Scalar scale = 1) const override;
280
281 protected:
282
283 /// Offset vector between the first and the second point.
285
286 /// Square length of the offset vector.
288
289 /// Penalty value.
291
292 /// State to finite the line at the first point.
293 bool finite0_ = false;
294
295 /// State to finite the line at the second point.
296 bool finite1_ = false;
297};
298
299/**
300 * This class implements a container holding constraints.
301 * @ingroup cvsynthesis
302 */
303class OCEAN_CV_SYNTHESIS_EXPORT Constraints
304{
305 public:
306
307 /**
308 * Definition of a vector holding constraints.
309 */
310 using ConstraintsVector = std::vector<std::unique_ptr<Constraint>>;
311
312 public:
313
314 /**
315 * Creates a new constraint container.
316 */
317 Constraints() = default;
318
319 /**
320 * Copy constructor.
321 * @param constraints The constraints to be copied
322 */
323 Constraints(const Constraints& constraints);
324
325 /**
326 * Default move constructor.
327 * @param constraints The constraints to be moved
328 */
329 Constraints(Constraints&& constraints) = default;
330
331 /**
332 * Copies a constraint container and applies an explicit scale factor.
333 * @param constraints The constraints to be copied
334 * @param scale The scale factor to be applied for each constraint to be copied, with range (0, infinity)
335 */
336 Constraints(const Constraints& constraints, const Scalar scale);
337
338 /**
339 * Destructs the constraint container.
340 */
341 ~Constraints() = default;
342
343 /**
344 * Adds a new constraint.
345 * The given constraint will be released by the container.
346 * @param constraint The constraint to be added
347 */
348 inline void addConstraint(std::unique_ptr<Constraint> constraint);
349
350 /**
351 * Returns the number of constraints.
352 * The number of constraints
353 */
354 inline size_t size() const;
355
356 /**
357 * Initializes the constraint decisions.
358 * @param mask The mask to create the decisions for, must be valid
359 * @param width The width of the mask in pixel
360 * @param height The height of the mask in pixel
361 * @param maskPaddingElements The number of padding elements at the end of each mask row, in elements, with range [0, infinity)
362 */
363 void initializeDecisions(const uint8_t* mask, const unsigned int width, const unsigned int height, const unsigned int maskPaddingElements) const;
364
365 /**
366 * Returns the cost for one inside point and one outside point.
367 * @param insideX Horizontal inside position
368 * @param insideY Vertical inside position
369 * @param outside The outside point
370 * @return Resulting cost
371 */
372 inline Scalar cost(const unsigned int insideX, const unsigned int insideY, const Vector2& outside) const;
373
374 /**
375 * Returns the cost for one inside point and one outside point.
376 * @param insideX Horizontal inside position
377 * @param insideY Vertical inside position
378 * @param outsideX Horizontal outside point
379 * @param outsideY Vertical outside point
380 * @return Resulting cost
381 */
382 inline Scalar cost(const unsigned int insideX, const unsigned int insideY, const unsigned int outsideX, const unsigned int outsideY) const;
383
384 /**
385 * Returns whether this container does not hold any constraint.
386 * @return True, if so
387 */
388 inline bool isEmpty() const;
389
390 /**
391 * Returns whether this container holds at least one constraint.
392 * @return True, if so
393 */
394 explicit inline operator bool() const;
395
396 /**
397 * Default move operator.
398 * @param constraints The constraints to be moved
399 * @return Reference to this object
400 */
401 Constraints& operator=(Constraints&& constraints) = default;
402
403 private:
404
405 /**
406 * Disabled assign operator.
407 * @return Reference to this object
408 */
409 Constraints& operator=(const Constraints& constraints) = delete;
410
411 private:
412
413 /// Vector holding the internal constraints.
415
416 /// Decision frame.
418};
419
422{
423 ocean_assert(impact_ >= 0);
424}
425
427{
428 return impact_;
429}
430
434 radiusParameter_(1 / (radius * Scalar(0.25)))
435{
436 // nothing to do here
437}
438
440{
441 return radius_;
442}
443
448{
449 ocean_assert(point0 != point1);
450 const Vector2 direction(point1 - point0);
451
452 const Scalar length = direction.length();
453 ocean_assert(Numeric::isNotEqualEps(length));
454
455 const Vector2 normal = direction.perpendicular() / length;
456 ocean_assert(Numeric::isEqual(normal.length(), 1));
457
458 const Scalar distance = normal * point0_;
459
460 parameter_ = Vector3(normal, -distance);
461}
462
463inline LineConstraint::LineConstraint(const LineConstraint& constraint, const Scalar scale) :
464 StructureConstraint(constraint.impact(), constraint.radius() * scale),
465 point0_(constraint.point0() * scale),
466 point1_(constraint.point1() * scale)
467{
468 ocean_assert(point0_ != point1_);
469 const Vector2 direction(point1_ - point0_);
470
471 const Scalar length = direction.length();
472 ocean_assert(Numeric::isNotEqualEps(length));
473
474 const Vector2 normal = direction.perpendicular() / length;
475 ocean_assert(Numeric::isEqual(normal.length(), 1));
476
477 const Scalar distance = normal * point0_;
478
479 parameter_ = Vector3(normal, -distance);
480}
481
482inline const Vector2& LineConstraint::point0() const
483{
484 return point0_;
485}
486
487inline const Vector2& LineConstraint::point1() const
488{
489 return point1_;
490}
491
493{
494 // lineParameter * Vector3(point, 1);
495 return parameter_.x() * point.x() + parameter_.y() * point.y() + parameter_.z();
496}
497
498inline Scalar LineConstraint::weight(const Scalar distance) const
499{
500 if (Numeric::abs(distance) > radius_)
501 {
502 return 0;
503 }
504
505 // impact * e ^ (-1/2 * (distance / (1/4 * radius)))
506 return impact_ * Numeric::exp(Scalar(-0.5) * Numeric::sqr(distance * radiusParameter_));
507}
508
509inline FiniteLineConstraint::FiniteLineConstraint(const Vector2& point0, const Vector2& point1, const Scalar impact, const Scalar radius, const Scalar penalty, const bool finite0, const bool finite1) :
516{
517 // nothing to do here
518}
519
521 LineConstraint(constraint.point0() * scale, constraint.point1() * scale, constraint.impact(), max(Scalar(2), constraint.radius() * scale)),
522 offset_((constraint.point1() - constraint.point0()) * scale),
524 penalty_(constraint.penalty() * scale),
525 finite0_(constraint.finite0_),
526 finite1_(constraint.finite1_)
527{
528 // nothing to do here
529}
530
532{
533 return penalty_;
534}
535
537{
538 return finite0_;
539}
540
542{
543 return finite1_;
544}
545
547{
548 if (!finite0_ && !finite1_)
549 {
551 }
552
553 const Scalar product = offset_ * (point - point0_);
554 return ((finite0_ && product < 0) || (finite1_ && product > offsetSquare_)) ? penalty_ : LineConstraint::infiniteLineDistance(point);
555}
556
557inline void Constraints::addConstraint(std::unique_ptr<Constraint> constraint)
558{
559 constraints_.emplace_back(std::move(constraint));
560}
561
562inline size_t Constraints::size() const
563{
564 return constraints_.size();
565}
566
567inline Scalar Constraints::cost(const unsigned int insideX, const unsigned int insideY, const Vector2& outside) const
568{
569 ocean_assert(decisionFrame_.isValid());
570
571 ocean_assert(insideX < decisionFrame_.width());
572 ocean_assert(insideY < decisionFrame_.height());
573
574 const uint8_t decision = decisionFrame_.constpixel<uint8_t>(insideX, insideY)[0];
575
576 if (decision == 0xFFu)
577 {
578 return 0;
579 }
580
581 ocean_assert((size_t)decision < constraints_.size());
582
583 return constraints_[decision]->cost(Vector2(Scalar(insideX), Scalar(insideY)), outside);
584}
585
586inline Scalar Constraints::cost(const unsigned int insideX, const unsigned int insideY, const unsigned int outsideX, const unsigned int outsideY) const
587{
588 return cost(insideX, insideY, Vector2(Scalar(outsideX), Scalar(outsideY)));
589}
590
591inline bool Constraints::isEmpty() const
592{
593 return constraints_.empty();
594}
595
596inline Constraints::operator bool() const
597{
598 return !constraints_.empty();
599}
600
601}
602
603}
604
605}
606
607#endif // META_OCEAN_CV_SYNTHESIS_CONSTRAINT_H
Constraint()=default
Creates an empty constraint.
friend class Constraints
Definition Constraint.h:35
virtual Scalar cost(const Vector2 &inside, const Vector2 &outside) const =0
Returns the cost for a given for two given points.
virtual std::unique_ptr< Constraint > copy(const Scalar scale=Scalar(1)) const =0
Creates a copy of this constraint by an optional scale parameter.
virtual ~Constraint()=default
Destructs this constraint.
virtual Scalar weight(const Vector2 &point) const =0
Returns the weight of this constraint according to a given point.
Constraint(const Scalar impact)
Creates an empty constraint.
Definition Constraint.h:420
Scalar impact() const
Returns the impact factor of this constraint.
Definition Constraint.h:426
Scalar impact_
Impact factor of this constraint.
Definition Constraint.h:89
void initializeDecisions(const uint8_t *mask, const unsigned int width, const unsigned int height, const unsigned int maskPaddingElements) const
Initializes the constraint decisions.
Frame decisionFrame_
Decision frame.
Definition Constraint.h:417
Constraints(const Constraints &constraints)
Copy constructor.
ConstraintsVector constraints_
Vector holding the internal constraints.
Definition Constraint.h:414
void addConstraint(std::unique_ptr< Constraint > constraint)
Adds a new constraint.
Definition Constraint.h:557
Constraints & operator=(Constraints &&constraints)=default
Default move operator.
size_t size() const
Returns the number of constraints.
Definition Constraint.h:562
Constraints & operator=(const Constraints &constraints)=delete
Disabled assign operator.
~Constraints()=default
Destructs the constraint container.
std::vector< std::unique_ptr< Constraint > > ConstraintsVector
Definition of a vector holding constraints.
Definition Constraint.h:310
Constraints(const Constraints &constraints, const Scalar scale)
Copies a constraint container and applies an explicit scale factor.
Constraints()=default
Creates a new constraint container.
Constraints(Constraints &&constraints)=default
Default move constructor.
Scalar cost(const unsigned int insideX, const unsigned int insideY, const Vector2 &outside) const
Returns the cost for one inside point and one outside point.
Definition Constraint.h:567
bool isEmpty() const
Returns whether this container does not hold any constraint.
Definition Constraint.h:591
Scalar penalty() const
Returns the penalty factor of this line constraint.
Definition Constraint.h:531
FiniteLineConstraint(const Vector2 &point0, const Vector2 &point1, const Scalar impact, const Scalar radius, const Scalar penalty, const bool finite0, const bool finite1)
Creates a new finite line constraint object.
Definition Constraint.h:509
Scalar offsetSquare_
Square length of the offset vector.
Definition Constraint.h:287
Vector2 offset_
Offset vector between the first and the second point.
Definition Constraint.h:284
Scalar penalty_
Penalty value.
Definition Constraint.h:290
bool finite1_
State to finite the line at the second point.
Definition Constraint.h:296
std::unique_ptr< Constraint > copy(const Scalar scale=1) const override
Creates a copy of this constraint by an optional scale parameter.
Scalar weight(const Vector2 &point) const override
Returns the weight of this constraint according to a given point.
bool finite1() const
Returns the finite state of the second point.
Definition Constraint.h:541
bool finite0() const
Returns the finite state of the first point.
Definition Constraint.h:536
Scalar cost(const Vector2 &inside, const Vector2 &outside) const override
Returns the cost for a given for two given points.
Scalar finiteLineDistance(const Vector2 &point) const
Returns the distance between a given point and this infinite line.
Definition Constraint.h:546
bool finite0_
State to finite the line at the first point.
Definition Constraint.h:293
LineConstraint(const Vector2 &point0, const Vector2 &point1, const Scalar impact, const Scalar radius)
Creates a new line constraint object for infinite lines.
Definition Constraint.h:444
const Vector2 & point0() const
Returns the first point of this line.
Definition Constraint.h:482
Vector3 parameter_
Normal (x, y) and distance (z) of the line.
Definition Constraint.h:208
Scalar infiniteLineDistance(const Vector2 &point) const
Returns the distance between a given point and this infinite line.
Definition Constraint.h:492
Scalar weight(const Vector2 &point) const override
Returns the weight of this constraint according to a given point.
Scalar cost(const Vector2 &inside, const Vector2 &outside) const override
Returns the cost for a given for two given points.
Vector2 point1_
Second point of the line.
Definition Constraint.h:205
Vector2 point0_
First point of the line.
Definition Constraint.h:202
std::unique_ptr< Constraint > copy(const Scalar scale=1) const override
Creates a copy of this constraint by an optional scale parameter.
const Vector2 & point1() const
Returns the second point of this line.
Definition Constraint.h:487
Scalar radius_
Impact radius of this structure constraint.
Definition Constraint.h:123
Scalar radiusParameter_
Radius parameter of this constraint: 1 / (1/4 * radius).
Definition Constraint.h:126
Scalar radius() const
Returns the radius of this constraint.
Definition Constraint.h:439
StructureConstraint(const Scalar impact, const Scalar radius)
Creates a new structure constraint object.
Definition Constraint.h:431
virtual Scalar weight(const Vector2 &point) const =0
Returns the weight of this constraint according to a given point.
This class implements Ocean's image class.
Definition Frame.h:1969
static Scalar exp(const Scalar value)
static Scalar abs(const Scalar value)
static bool isEqual(const Scalar first, const Scalar second)
static constexpr Scalar sqr(const Scalar value)
static constexpr bool isNotEqualEps(const Scalar value)
const T & x() const noexcept
Returns the x value.
Definition Vector2.h:703
const T & y() const noexcept
Returns the y value.
Definition Vector2.h:715
T length() const
Returns the length of the vector.
Definition Vector2.h:620
VectorT2< T > perpendicular() const
Returns a vector perpendicular to this vectors.
Definition Vector2.h:555
unsigned int sqr(const char value)
Returns the square value of a given value.
Definition base/Utilities.h:1099
VectorT2< Scalar > Vector2
Definition of a 2D vector.
Definition Vector2.h:28
VectorT3< Scalar > Vector3
Definition of a 3D vector.
Definition Vector3.h:29
float Scalar
Definition of a scalar type.
Definition Math.h:129
Namespace of the CV Synthesis library.
Definition Constraint.h:25
Namespace of the CV library.
Definition Advanced.h:17
The namespace covering the entire Ocean framework.
Definition Accessor.h:15