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.InhomogeneousPoint2D;
19 import com.irurueta.geometry.Point2D;
20
21 import java.io.Serializable;
22 import java.util.ArrayList;
23 import java.util.List;
24
25 /**
26 * Contains coordinates of ideal points for a QR code pattern version 2.
27 * When physical size of a 2D QR code is known, its corner markets can be
28 * used for camera calibration purposes.
29 * This pattern takes into account that a QR code has 3 finder patterns and
30 * 1 alignment pattern.
31 * The points returned by this pattern indicates where should these points be
32 * placed for a QR code having provided size.
33 * Points are returned in the following order:
34 * - Bottom-left finder pattern.
35 * - Top-left finder pattern (located at origin of coordinates 0,0).
36 * - Top-right finder pattern.
37 * - Bottom-right alignment pattern.
38 * <p>
39 * The contents of this class are based on:
40 * <a href="http://www.thonky.com/qr-code-tutorial/module-placement-matrix/">
41 * http://www.thonky.com/qr-code-tutorial/module-placement-matrix/
42 * </a>
43 */
44 public class QRPattern2D extends Pattern2D implements Serializable {
45
46 /**
47 * Returns number of points used by this 2D pattern.
48 */
49 public static final int NUMBER_OF_POINTS = 4;
50
51 /**
52 * Supported QR code version.
53 */
54 public static final int QR_VERSION = 2;
55
56 /**
57 * Default number of horizontal and vertical modules (e.q. squares shown in QR).
58 * This follows expression: ((QR_VERSION - 1) * 4) + 21
59 */
60 public static final int NUMBER_OF_MODULES = 25;
61
62 /**
63 * Offset of origin expressed in modules so that top-left finder pattern
64 * is placed at 0,0.
65 */
66 public static final int ORIGIN_OFFSET = 4;
67
68 /**
69 * Default QR code width expressed in meters.
70 * This value is used to obtain a reference physical measure.
71 */
72 public static final double DEFAULT_QR_CODE_WIDTH = 1.1e-2; // 1.1 cm
73
74 /**
75 * Default QR code height expressed in meters.
76 * This value is used to obtain a reference physical measure.
77 */
78 public static final double DEFAULT_QR_CODE_HEIGHT = 1.1e-2; // 1.1 cm
79
80 /**
81 * QR code width expressed in meters.
82 * This value is used to obtain a reference physical measure.
83 */
84 private double codeWidth;
85
86 /**
87 * QR code height expressed in meters.
88 * This value is used to obtain a reference physical measure.
89 */
90 private double codeHeight;
91
92 /**
93 * Constructor.
94 */
95 public QRPattern2D() {
96 codeWidth = DEFAULT_QR_CODE_WIDTH;
97 codeHeight = DEFAULT_QR_CODE_HEIGHT;
98 }
99
100 /**
101 * Returns QR code width expressed in meters.
102 * This value is used to obtain a reference physical measure.
103 *
104 * @return QR code width expressed in meters.
105 */
106 public double getCodeWidth() {
107 return codeWidth;
108 }
109
110 /**
111 * Sets QR code width expressed in meters.
112 * This value is used to obtain a reference physical measure.
113 *
114 * @param codeWidth QR code width expressed in meters.
115 * @throws IllegalArgumentException if provided value is zero or negative.
116 */
117 public void setCodeWidth(final double codeWidth) {
118 if (codeWidth <= 0.0) {
119 throw new IllegalArgumentException();
120 }
121
122 this.codeWidth = codeWidth;
123 }
124
125 /**
126 * Returns QR code height expressed in meters.
127 * This value is used to obtain a reference physical measure.
128 *
129 * @return QR code height expressed in meters.
130 */
131 public double getCodeHeight() {
132 return codeHeight;
133 }
134
135 /**
136 * Sets QR code height expressed in meters.
137 * This value is used to obtain a reference physical measure.
138 *
139 * @param codeHeight QR code width expressed in meters.
140 * @throws IllegalArgumentException if provided value is zero or negative.
141 */
142 public void setCodeHeight(final double codeHeight) {
143 if (codeHeight <= 0.0) {
144 throw new IllegalArgumentException();
145 }
146
147 this.codeHeight = codeHeight;
148 }
149
150 /**
151 * Returns ideal points coordinates contained in a QR 2D pattern and
152 * expressed in meters. These values are used for calibration purposes
153 *
154 * @return ideal points coordinates.
155 */
156 @Override
157 public List<Point2D> getIdealPoints() {
158 final var points = new ArrayList<Point2D>();
159
160 // The size of a QR code (expressed in modules, i.e. each small square)
161 // can be calculated with the formula (((V-1)*4)+21), where V is the QR
162 // code version.
163 // For version 2, then the size will be 25 modules by 25 modules, where
164 // each module will be the smallest square that can be represented in the
165 // QR code and whose size will be equal to mCodeWidth/25 per
166 // mCodeHeight/25 expressed in meters (since both mCodeWidth and
167 // mCodeHeight are expressed in meters)
168
169 // Each finder pattern consists of an outer 7 modules by 7 modules outer
170 // black square, with an inner white square being 5x5 and finally and
171 // inner black square which is 3x3.
172
173 // Hence, assuming the top-left finder is at location 0,0 (which is
174 // indeed the module 3,3 assuming modules positions start at 1).
175 // Then the top-right finder pattern is located at:
176 // ([(((V-1)*4)+21) - 7], 0), where we have subtracted 7 to the QR code
177 // width expressed in modules to account for the fact that finder modules
178 // are centered at 3x3 (we subtract 4 modules for top-left plus 3 modules
179 // for top-right). For version 2 this is equal to (18, 0)
180 // Likewise, bottom-left module will be placed at
181 // (0, [(((V-1)*4)+21) - 7]). For version 2 this is equal to (0, 18)
182
183 // The alignment patterns are 5x5 black squares containing a
184 // 3x3 white inner square, which contains a 1x2 black square
185
186 // On QR version 2 alignment patterns are placed with a 6x6 module margin
187 // respect to QR code boundaries. Because bottom-left, top-left and
188 // top-right alignment patterns would overlap the finder patterns,
189 // version 2 only includes the bottom right alignment pattern, which
190 // is located at ([(((V-1)*4)+21) - 7 - 3], [(((V-1)*4)+21) - 7 - 3]),
191 // so for version 2 this is equal to (15, 15)
192
193 final var moduleWidth = codeWidth / NUMBER_OF_MODULES;
194 final var moduleHeight = codeHeight / NUMBER_OF_MODULES;
195
196 // below is equivalent to [(((V-1)*4)+21) - 7] = 18
197 final var finderModulePos = NUMBER_OF_MODULES - 3 - ORIGIN_OFFSET;
198 // below is always 15
199 final var alignModulePos = finderModulePos - 3;
200
201 // bottom-left finder pattern
202 points.add(new InhomogeneousPoint2D(0.0, finderModulePos * moduleHeight));
203 // top-left finder pattern
204 points.add(new InhomogeneousPoint2D(0.0, 0.0));
205 // top-right finder pattern
206 points.add(new InhomogeneousPoint2D(finderModulePos * moduleWidth, 0.0));
207
208 // bottom-right alignment pattern
209 points.add(new InhomogeneousPoint2D(alignModulePos * moduleWidth, alignModulePos * moduleHeight));
210
211 return points;
212 }
213
214 /**
215 * Returns number of 2D points used by this pattern.
216 *
217 * @return number of 2D points used by this pattern.
218 */
219 @Override
220 public int getNumberOfPoints() {
221 return NUMBER_OF_POINTS;
222 }
223
224 /**
225 * Gets pattern type.
226 *
227 * @return pattern type.
228 */
229 @Override
230 public Pattern2DType getType() {
231 return Pattern2DType.QR;
232 }
233 }