1 /*
2 * Copyright (C) 2015 Alberto Irurueta Carro (alberto@irurueta.com)
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package com.irurueta.ar.calibration;
17
18 import com.irurueta.geometry.NotSupportedException;
19 import com.irurueta.geometry.Point2D;
20
21 import java.util.ArrayList;
22 import java.util.List;
23
24 /**
25 * This class accounts for any possible distortion that might occur on 2D
26 * points. This might occur for instance when using cameras that produce
27 * additional distortion (such as radial distortion) not modelled in the general
28 * camera model.
29 * This class is abstract, specific implementations for each kind of supported
30 * distortion exists.
31 */
32 public abstract class Distortion {
33
34 /**
35 * Distorts provided 2D point.
36 *
37 * @param undistortedPoint undistorted point to be distorted.
38 * @return distorted point.
39 * @throws NotSupportedException raised if distortion implementation does
40 * not support distorting points.
41 * @throws DistortionException raised if distortion computation failed.
42 */
43 public Point2D distort(final Point2D undistortedPoint) throws NotSupportedException, DistortionException {
44 final var distortedPoint = Point2D.create();
45 distort(undistortedPoint, distortedPoint);
46 return distortedPoint;
47 }
48
49 /**
50 * Distorts provided 2D points.
51 *
52 * @param undistortedPoints list of undistorted points to be distorted.
53 * @return distorted points.
54 * @throws NotSupportedException raised if distortion implementation does
55 * not support distorting points.
56 * @throws DistortionException raised if distortion computation failed.
57 */
58 public List<Point2D> distort(final List<Point2D> undistortedPoints) throws NotSupportedException,
59 DistortionException {
60 final var size = undistortedPoints.size();
61 final var distortedPoints = new ArrayList<Point2D>(size);
62 for (var i = 0; i < size; i++) {
63 distortedPoints.add(Point2D.create());
64 }
65 distort(undistortedPoints, distortedPoints);
66 return distortedPoints;
67 }
68
69 /**
70 * Distorts provided 2D points and stores them into provided distorted
71 * points list.
72 *
73 * @param undistortedPoints list of undistorted points to be distorted.
74 * @param distortedPoints distorted points where result is stored.
75 * @throws IllegalArgumentException if both lists don't have the same size.
76 * @throws NotSupportedException raised if distortion implementation does
77 * not support distorting points.
78 * @throws DistortionException raised if distortion computation failed.
79 */
80 public void distort(final List<Point2D> undistortedPoints, final List<Point2D> distortedPoints)
81 throws NotSupportedException, DistortionException {
82 if (undistortedPoints.size() != distortedPoints.size()) {
83 throw new IllegalArgumentException();
84 }
85
86 final var it1 = undistortedPoints.iterator();
87 final var it2 = distortedPoints.iterator();
88 while (it1.hasNext() && it2.hasNext()) {
89 var undistortedPoint = it1.next();
90 var distortedPoint = it2.next();
91 distort(undistortedPoint, distortedPoint);
92 }
93 }
94
95 /**
96 * Un-distorts provided 2D point.
97 *
98 * @param distortedPoint distorted point to be undistorted
99 * @return undistorted point.
100 * @throws NotSupportedException raised if distortion implementation does
101 * not support un-distorting points.
102 * @throws DistortionException raised if un-distortion computation failed.
103 */
104 public Point2D undistort(final Point2D distortedPoint) throws NotSupportedException, DistortionException {
105 final var undistortedPoint = Point2D.create();
106 undistort(distortedPoint, undistortedPoint);
107 return undistortedPoint;
108 }
109
110 /**
111 * Un-distorts provided 2D points.
112 *
113 * @param distortedPoints list of distorted points to be undistorted
114 * @return undistorted points.
115 * @throws NotSupportedException raised if distortion implementation does
116 * not support un-distorting points.
117 * @throws DistortionException raised if un-distortion computation failed.
118 */
119 public List<Point2D> undistort(final List<Point2D> distortedPoints) throws NotSupportedException,
120 DistortionException {
121 final var size = distortedPoints.size();
122 final var undistortedPoints = new ArrayList<Point2D>(size);
123 for (var i = 0; i < size; i++) {
124 undistortedPoints.add(Point2D.create());
125 }
126 undistort(distortedPoints, undistortedPoints);
127 return undistortedPoints;
128 }
129
130 /**
131 * Un-distorts provided 2D points and stores them into provided undistorted
132 * points list.
133 *
134 * @param distortedPoints list of distorted points to be undistorted.
135 * @param undistortedPoints undistorted points where result is stored.
136 * @throws IllegalArgumentException if both lists don't have the same size.
137 * @throws NotSupportedException raised if distortion implementation does
138 * not support un-distorting points.
139 * @throws DistortionException raised if un-distortion computation failed.
140 */
141 public void undistort(
142 final List<Point2D> distortedPoints, final List<Point2D> undistortedPoints) throws NotSupportedException,
143 DistortionException {
144 if (distortedPoints.size() != undistortedPoints.size()) {
145 throw new IllegalArgumentException();
146 }
147
148 final var it1 = distortedPoints.iterator();
149 final var it2 = undistortedPoints.iterator();
150 while (it1.hasNext() && it2.hasNext()) {
151 final var distortedPoint = it1.next();
152 final var undistortedPoint = it2.next();
153 undistort(distortedPoint, undistortedPoint);
154 }
155 }
156
157 /**
158 * Distorts provided 2D point and stores result into provided distorted
159 * point.
160 *
161 * @param undistortedPoint undistorted point to be undistorted.
162 * @param distortedPoint distorted point where result is stored.
163 * @throws NotSupportedException raised if distortion implementation does
164 * not support distorting points.
165 * @throws DistortionException raised if distortion computation failed.
166 */
167 public abstract void distort(final Point2D undistortedPoint, final Point2D distortedPoint)
168 throws NotSupportedException, DistortionException;
169
170 /**
171 * Un-distorts provided 2D point and stores result into provided undistorted
172 * point.
173 *
174 * @param distortedPoint distorted point to be undistorted.
175 * @param undistortedPoint undistorted point where result is stored.
176 * @throws NotSupportedException raised if distortion implementation does
177 * not support un-distorting points.
178 * @throws DistortionException raised if un-distortion computation failed.
179 */
180 public abstract void undistort(final Point2D distortedPoint, final Point2D undistortedPoint)
181 throws NotSupportedException, DistortionException;
182
183 /**
184 * Indicates whether this instance can distort points.
185 *
186 * @return true if points can be distorted, false otherwise.
187 */
188 public abstract boolean canDistort();
189
190 /**
191 * Indicates whether this instance can un-distort points.
192 *
193 * @return true if points can be undistorted, false otherwise.
194 */
195 public abstract boolean canUndistort();
196
197 /**
198 * Returns kind of distortion.
199 *
200 * @return kind of distortion.
201 */
202 public abstract DistortionKind getKind();
203 }