Coverage for characterisation/correction.py: 64%

1""" 

2Colour Correction 

3================= 

4 

5Define objects for colour correction, including methods for colour matching 

6between images: 

7 

8- :func:`colour.characterisation.matrix_augmented_Cheung2004`: Perform 

9 polynomial expansion using *Cheung, Westland, Connah and Ripamonti (2004)* 

10 method. 

11- :func:`colour.characterisation.polynomial_expansion_Finlayson2015`: 

12 Perform polynomial expansion using *Finlayson, MacKiewicz and Hurlbert 

13 (2015)* method. 

14- :func:`colour.characterisation.polynomial_expansion_Vandermonde`: Perform 

15 polynomial expansion using *Vandermonde* method. 

16- :attr:`colour.POLYNOMIAL_EXPANSION_METHODS`: Supported polynomial 

17 expansion methods. 

18- :func:`colour.polynomial_expansion`: Perform polynomial expansion of 

19 :math:`a` array. 

20- :func:`colour.characterisation.matrix_colour_correction_Cheung2004`: 

21 Compute colour correction matrix using *Cheung et al. (2004)* method. 

22- :func:`colour.characterisation.matrix_colour_correction_Finlayson2015`: 

23 Compute colour correction matrix using *Finlayson et al. (2015)* method. 

24- :func:`colour.characterisation.matrix_colour_correction_Vandermonde`: 

25 Compute colour correction matrix using *Vandermonde* method. 

26- :attr:`colour.MATRIX_COLOUR_CORRECTION_METHODS`: Supported colour 

27 correction matrix methods. 

28- :func:`colour.matrix_colour_correction`: Compute colour correction matrix 

29 from :math:`M_T` colour array to :math:`M_R` colour array. 

30- :func:`colour.apply_matrix_colour_correction_Cheung2004`: Apply colour 

31 correction matrix computed using *Cheung et al. (2004)* method. 

32- :func:`colour.apply_matrix_colour_correction_Finlayson2015`: Apply colour 

33 correction matrix computed using *Finlayson et al. (2015)* method. 

34- :func:`colour.apply_matrix_colour_correction_Vandermonde`: Apply colour 

35 correction matrix computed using *Vandermonde* method. 

36- :attr:`colour.APPLY_MATRIX_COLOUR_CORRECTION_METHODS`: Supported methods 

37 to apply colour correction matrices. 

38- :func:`colour.apply_matrix_colour_correction`: Apply colour correction 

39 matrix. 

40- :func:`colour.characterisation.colour_correction_Cheung2004`: Perform 

41 colour correction using *Cheung et al. (2004)* method. 

42- :func:`colour.characterisation.colour_correction_Finlayson2015`: Perform 

43 colour correction using *Finlayson et al. (2015)* method. 

44- :func:`colour.characterisation.colour_correction_Vandermonde`: Perform 

45 colour correction using *Vandermonde* method. 

46- :attr:`colour.COLOUR_CORRECTION_METHODS`: Supported colour correction 

47 methods. 

48- :func:`colour.colour_correction`: Perform colour correction of *RGB* 

49 colourspace array using colour correction matrix from :math:`M_T` colour 

50 array to :math:`M_R` colour array. 

51 

52References 

53---------- 

54- :cite:`Cheung2004` : Cheung, V., Westland, S., Connah, D., & Ripamonti, C. 

55 (2004). A comparative study of the characterisation of colour cameras by 

56 means of neural networks and polynomial transforms. Coloration Technology, 

57 120(1), 19-25. doi:10.1111/j.1478-4408.2004.tb00201.x 

58- :cite:`Finlayson2015` : Finlayson, G. D., MacKiewicz, M., & Hurlbert, A. 

59 (2015). Color Correction Using Root-Polynomial Regression. IEEE 

60 Transactions on Image Processing, 24(5), 1460-1470. 

61 doi:10.1109/TIP.2015.2405336 

62- :cite:`Westland2004` : Westland, S., & Ripamonti, C. (2004). Table 8.2. In 

63 Computational Colour Science Using MATLAB (1st ed., p. 137). John Wiley & 

64 Sons, Ltd. doi:10.1002/0470020326 

65- :cite:`Wikipedia2003e` : Wikipedia. (2003). Vandermonde matrix. Retrieved 

66 May 2, 2018, from https://en.wikipedia.org/wiki/Vandermonde_matrix 

67""" 

68 

69from __future__ import annotations 

70 

71import typing 

72 

73import numpy as np 

74 

75from colour.algebra import least_square_mapping_MoorePenrose, spow 

76 

77if typing.TYPE_CHECKING: 

78 from colour.hints import Any, ArrayLike, Literal, NDArrayFloat 

79 

80from colour.utilities import ( 

81 CanonicalMapping, 

82 as_float, 

83 as_float_array, 

84 as_int, 

85 closest, 

86 filter_kwargs, 

87 ones, 

88 tsplit, 

89 tstack, 

90 validate_method, 

91) 

92 

93__author__ = "Colour Developers" 

94__copyright__ = "Copyright 2013 Colour Developers" 

95__license__ = "BSD-3-Clause - https://opensource.org/licenses/BSD-3-Clause" 

96__maintainer__ = "Colour Developers" 

97__email__ = "colour-developers@colour-science.org" 

98__status__ = "Production" 

99 

100__all__ = [ 

101 "matrix_augmented_Cheung2004", 

102 "polynomial_expansion_Finlayson2015", 

103 "polynomial_expansion_Vandermonde", 

104 "POLYNOMIAL_EXPANSION_METHODS", 

105 "polynomial_expansion", 

106 "matrix_colour_correction_Cheung2004", 

107 "matrix_colour_correction_Finlayson2015", 

108 "matrix_colour_correction_Vandermonde", 

109 "MATRIX_COLOUR_CORRECTION_METHODS", 

110 "matrix_colour_correction", 

111 "apply_matrix_colour_correction_Cheung2004", 

112 "apply_matrix_colour_correction_Finlayson2015", 

113 "apply_matrix_colour_correction_Vandermonde", 

114 "APPLY_MATRIX_COLOUR_CORRECTION_METHODS", 

115 "apply_matrix_colour_correction", 

116 "colour_correction_Cheung2004", 

117 "colour_correction_Finlayson2015", 

118 "colour_correction_Vandermonde", 

119 "COLOUR_CORRECTION_METHODS", 

120 "colour_correction", 

121] 

122 

123 

124def matrix_augmented_Cheung2004( 

125 RGB: ArrayLike, 

126 terms: Literal[3, 4, 5, 7, 8, 10, 11, 14, 16, 17, 19, 20, 22, 35] | int = 3, 

127) -> NDArrayFloat: 

128 """ 

129 Perform polynomial expansion of *RGB* colourspace array using 

130 *Cheung et al. (2004)* method. 

131 

132 Parameters 

133 ---------- 

134 RGB 

135 *RGB* colourspace array to expand using polynomial expansion. 

136 terms 

137 Number of terms of the expanded polynomial. 

138 

139 Returns 

140 ------- 

141 :class:`numpy.ndarray` 

142 Polynomial-expanded *RGB* colourspace array. 

143 

144 Notes 

145 ----- 

146 - This definition combines the augmented matrices specified in 

147 :cite:`Cheung2004` and :cite:`Westland2004`. 

148 

149 References 

150 ---------- 

151 :cite:`Cheung2004`, :cite:`Westland2004` 

152 

153 Examples 

154 -------- 

155 >>> RGB = np.array([0.17224810, 0.09170660, 0.06416938]) 

156 >>> matrix_augmented_Cheung2004(RGB, terms=5) # doctest: +ELLIPSIS 

157 array([ 0.1722481..., 0.0917066..., 0.0641693..., 0.0010136..., 1...]) 

158 """ 

159 

160 RGB = as_float_array(RGB) 

161 

162 R, G, B = tsplit(RGB) 

163 tail = ones(R.shape) 

164 

165 existing_terms = np.array([3, 4, 5, 7, 8, 10, 11, 14, 16, 17, 19, 20, 22, 35]) 

166 closest_terms = as_int(closest(existing_terms, terms)) 

167 if closest_terms != terms: 

168 error = ( 

169 f'"Cheung et al. (2004)" method does not define an augmented ' 

170 f"matrix with {terms} terms, closest augmented matrix has " 

171 f"{closest_terms} terms!" 

172 ) 

173 

174 raise ValueError(error) 

175 

176 if terms == 3: 

177 expansion = RGB 

178 elif terms == 4: 

179 expansion = tstack([R, G, B, tail]) 

180 elif terms == 5: 

181 expansion = tstack( 

182 [ 

183 R, 

184 G, 

185 B, 

186 R * G * B, 

187 tail, 

188 ] 

189 ) 

190 elif terms == 7: 

191 expansion = tstack( 

192 [ 

193 R, 

194 G, 

195 B, 

196 R * G, 

197 R * B, 

198 G * B, 

199 tail, 

200 ] 

201 ) 

202 elif terms == 8: 

203 expansion = tstack( 

204 [ 

205 R, 

206 G, 

207 B, 

208 R * G, 

209 R * B, 

210 G * B, 

211 R * G * B, 

212 tail, 

213 ] 

214 ) 

215 elif terms == 10: 

216 expansion = tstack( 

217 [ 

218 R, 

219 G, 

220 B, 

221 R * G, 

222 R * B, 

223 G * B, 

224 R**2, 

225 G**2, 

226 B**2, 

227 tail, 

228 ] 

229 ) 

230 elif terms == 11: 

231 expansion = tstack( 

232 [ 

233 R, 

234 G, 

235 B, 

236 R * G, 

237 R * B, 

238 G * B, 

239 R**2, 

240 G**2, 

241 B**2, 

242 R * G * B, 

243 tail, 

244 ] 

245 ) 

246 elif terms == 14: 

247 expansion = tstack( 

248 [ 

249 R, 

250 G, 

251 B, 

252 R * G, 

253 R * B, 

254 G * B, 

255 R**2, 

256 G**2, 

257 B**2, 

258 R * G * B, 

259 R**3, 

260 G**3, 

261 B**3, 

262 tail, 

263 ] 

264 ) 

265 elif terms == 16: 

266 expansion = tstack( 

267 [ 

268 R, 

269 G, 

270 B, 

271 R * G, 

272 R * B, 

273 G * B, 

274 R**2, 

275 G**2, 

276 B**2, 

277 R * G * B, 

278 R**2 * G, 

279 G**2 * B, 

280 B**2 * R, 

281 R**3, 

282 G**3, 

283 B**3, 

284 ] 

285 ) 

286 elif terms == 17: 

287 expansion = tstack( 

288 [ 

289 R, 

290 G, 

291 B, 

292 R * G, 

293 R * B, 

294 G * B, 

295 R**2, 

296 G**2, 

297 B**2, 

298 R * G * B, 

299 R**2 * G, 

300 G**2 * B, 

301 B**2 * R, 

302 R**3, 

303 G**3, 

304 B**3, 

305 tail, 

306 ] 

307 ) 

308 elif terms == 19: 

309 expansion = tstack( 

310 [ 

311 R, 

312 G, 

313 B, 

314 R * G, 

315 R * B, 

316 G * B, 

317 R**2, 

318 G**2, 

319 B**2, 

320 R * G * B, 

321 R**2 * G, 

322 G**2 * B, 

323 B**2 * R, 

324 R**2 * B, 

325 G**2 * R, 

326 B**2 * G, 

327 R**3, 

328 G**3, 

329 B**3, 

330 ] 

331 ) 

332 elif terms == 20: 

333 expansion = tstack( 

334 [ 

335 R, 

336 G, 

337 B, 

338 R * G, 

339 R * B, 

340 G * B, 

341 R**2, 

342 G**2, 

343 B**2, 

344 R * G * B, 

345 R**2 * G, 

346 G**2 * B, 

347 B**2 * R, 

348 R**2 * B, 

349 G**2 * R, 

350 B**2 * G, 

351 R**3, 

352 G**3, 

353 B**3, 

354 tail, 

355 ] 

356 ) 

357 elif terms == 22: 

358 expansion = tstack( 

359 [ 

360 R, 

361 G, 

362 B, 

363 R * G, 

364 R * B, 

365 G * B, 

366 R**2, 

367 G**2, 

368 B**2, 

369 R * G * B, 

370 R**2 * G, 

371 G**2 * B, 

372 B**2 * R, 

373 R**2 * B, 

374 G**2 * R, 

375 B**2 * G, 

376 R**3, 

377 G**3, 

378 B**3, 

379 R**2 * G * B, 

380 R * G**2 * B, 

381 R * G * B**2, 

382 ] 

383 ) 

384 elif terms == 35: 

385 expansion = tstack( 

386 [ 

387 R, 

388 G, 

389 B, 

390 R * G, 

391 R * B, 

392 G * B, 

393 R**2, 

394 G**2, 

395 B**2, 

396 R * G * B, 

397 R**2 * G, 

398 G**2 * B, 

399 B**2 * R, 

400 R**2 * B, 

401 G**2 * R, 

402 B**2 * G, 

403 R**3, 

404 G**3, 

405 B**3, 

406 R**3 * G, 

407 R**3 * B, 

408 G**3 * R, 

409 G**3 * B, 

410 B**3 * R, 

411 B**3 * G, 

412 R**2 * G * B, 

413 R * G**2 * B, 

414 R * G * B**2, 

415 R**2 * G**2, 

416 R**2 * B**2, 

417 G**2 * B**2, 

418 R**4, 

419 G**4, 

420 B**4, 

421 tail, 

422 ] 

423 ) 

424 

425 return expansion 

426 

427 

428def polynomial_expansion_Finlayson2015( 

429 RGB: ArrayLike, 

430 degree: Literal[1, 2, 3, 4] | int = 1, 

431 root_polynomial_expansion: bool = True, 

432) -> NDArrayFloat: 

433 """ 

434 Perform polynomial expansion of the specified *RGB* colourspace 

435 array using the *Finlayson et al. (2015)* method. 

436 

437 Parameters 

438 ---------- 

439 RGB 

440 *RGB* colourspace array to expand using polynomial expansion. 

441 degree 

442 Expanded polynomial degree. 

443 root_polynomial_expansion 

444 Whether to use the root-polynomials set for the expansion. 

445 

446 Returns 

447 ------- 

448 :class:`numpy.ndarray` 

449 Polynomial-expanded *RGB* colourspace array. 

450 

451 References 

452 ---------- 

453 :cite:`Finlayson2015` 

454 

455 Examples 

456 -------- 

457 >>> RGB = np.array([0.17224810, 0.09170660, 0.06416938]) 

458 >>> polynomial_expansion_Finlayson2015(RGB, degree=2) # doctest: +ELLIPSIS 

459 array([ 0.1722481..., 0.0917066..., 0.0641693..., 0.1256832..., \ 

4600.0767121..., 

461 0.1051335...]) 

462 """ 

463 

464 RGB = as_float_array(RGB) 

465 

466 R, G, B = tsplit(RGB) 

467 

468 # TODO: Generalise polynomial expansion. 

469 existing_degrees = np.array([1, 2, 3, 4]) 

470 closest_degree = as_int(closest(existing_degrees, degree)) 

471 if closest_degree != degree: 

472 error = ( 

473 f'"Finlayson et al. (2015)" method does not define a polynomial ' 

474 f"expansion for {degree} degree, closest polynomial expansion is " 

475 f"{closest_degree} degree!" 

476 ) 

477 

478 raise ValueError(error) 

479 

480 if degree == 1: 

481 expansion = RGB 

482 elif degree == 2: 

483 if root_polynomial_expansion: 

484 expansion = tstack( 

485 [ 

486 as_float(R), 

487 as_float(G), 

488 as_float(B), 

489 spow(R * G, 1 / 2), 

490 spow(G * B, 1 / 2), 

491 spow(R * B, 1 / 2), 

492 ] 

493 ) 

494 

495 else: 

496 expansion = tstack( 

497 [ 

498 R, 

499 G, 

500 B, 

501 R**2, 

502 G**2, 

503 B**2, 

504 R * G, 

505 G * B, 

506 R * B, 

507 ] 

508 ) 

509 elif degree == 3: 

510 if root_polynomial_expansion: 

511 expansion = tstack( 

512 [ 

513 as_float(R), 

514 as_float(G), 

515 as_float(B), 

516 spow(R * G, 1 / 2), 

517 spow(G * B, 1 / 2), 

518 spow(R * B, 1 / 2), 

519 spow(R * G**2, 1 / 3), 

520 spow(G * B**2, 1 / 3), 

521 spow(R * B**2, 1 / 3), 

522 spow(G * R**2, 1 / 3), 

523 spow(B * G**2, 1 / 3), 

524 spow(B * R**2, 1 / 3), 

525 spow(R * G * B, 1 / 3), 

526 ] 

527 ) 

528 else: 

529 expansion = tstack( 

530 [ 

531 R, 

532 G, 

533 B, 

534 R**2, 

535 G**2, 

536 B**2, 

537 R * G, 

538 G * B, 

539 R * B, 

540 R**3, 

541 G**3, 

542 B**3, 

543 R * G**2, 

544 G * B**2, 

545 R * B**2, 

546 G * R**2, 

547 B * G**2, 

548 B * R**2, 

549 R * G * B, 

550 ] 

551 ) 

552 elif degree == 4: 

553 if root_polynomial_expansion: 

554 expansion = tstack( 

555 [ 

556 as_float(R), 

557 as_float(G), 

558 as_float(B), 

559 spow(R * G, 1 / 2), 

560 spow(G * B, 1 / 2), 

561 spow(R * B, 1 / 2), 

562 spow(R * G**2, 1 / 3), 

563 spow(G * B**2, 1 / 3), 

564 spow(R * B**2, 1 / 3), 

565 spow(G * R**2, 1 / 3), 

566 spow(B * G**2, 1 / 3), 

567 spow(B * R**2, 1 / 3), 

568 spow(R * G * B, 1 / 3), 

569 spow(R**3 * G, 1 / 4), 

570 spow(R**3 * B, 1 / 4), 

571 spow(G**3 * R, 1 / 4), 

572 spow(G**3 * B, 1 / 4), 

573 spow(B**3 * R, 1 / 4), 

574 spow(B**3 * G, 1 / 4), 

575 spow(R**2 * G * B, 1 / 4), 

576 spow(G**2 * R * B, 1 / 4), 

577 spow(B**2 * R * G, 1 / 4), 

578 ] 

579 ) 

580 else: 

581 expansion = tstack( 

582 [ 

583 R, 

584 G, 

585 B, 

586 R**2, 

587 G**2, 

588 B**2, 

589 R * G, 

590 G * B, 

591 R * B, 

592 R**3, 

593 G**3, 

594 B**3, 

595 R * G**2, 

596 G * B**2, 

597 R * B**2, 

598 G * R**2, 

599 B * G**2, 

600 B * R**2, 

601 R * G * B, 

602 R**4, 

603 G**4, 

604 B**4, 

605 R**3 * G, 

606 R**3 * B, 

607 G**3 * R, 

608 G**3 * B, 

609 B**3 * R, 

610 B**3 * G, 

611 R**2 * G**2, 

612 G**2 * B**2, 

613 R**2 * B**2, 

614 R**2 * G * B, 

615 G**2 * R * B, 

616 B**2 * R * G, 

617 ] 

618 ) 

619 

620 return expansion 

621 

622 

623def polynomial_expansion_Vandermonde(a: ArrayLike, degree: int = 1) -> NDArrayFloat: 

624 """ 

625 Perform polynomial expansion of the specified :math:`a` array using the 

626 *Vandermonde* method. 

627 

628 Parameters 

629 ---------- 

630 a 

631 Array :math:`a` to expand using polynomial expansion. 

632 degree 

633 Degree of the expanded polynomial. 

634 

635 Returns 

636 ------- 

637 :class:`numpy.ndarray` 

638 Polynomial-expanded :math:`a` array. 

639 

640 References 

641 ---------- 

642 :cite:`Wikipedia2003e` 

643 

644 Examples 

645 -------- 

646 >>> RGB = np.array([0.17224810, 0.09170660, 0.06416938]) 

647 >>> polynomial_expansion_Vandermonde(RGB) # doctest: +ELLIPSIS 

648 array([ 0.1722481 , 0.0917066 , 0.06416938, 1. ]) 

649 """ 

650 

651 a = as_float_array(a) 

652 

653 a_e = np.transpose(np.vander(np.ravel(a), int(degree) + 1)) 

654 a_e = np.hstack(list(np.reshape(a_e, (a_e.shape[0], -1, 3)))) 

655 

656 return np.squeeze(a_e[:, 0 : a_e.shape[-1] - a.shape[-1] + 1]) 

657 

658 

659POLYNOMIAL_EXPANSION_METHODS: CanonicalMapping = CanonicalMapping( 

660 { 

661 "Cheung 2004": matrix_augmented_Cheung2004, 

662 "Finlayson 2015": polynomial_expansion_Finlayson2015, 

663 "Vandermonde": polynomial_expansion_Vandermonde, 

664 } 

665) 

666POLYNOMIAL_EXPANSION_METHODS.__doc__ = """ 

667Supported polynomial expansion methods. 

668 

669References 

670---------- 

671:cite:`Cheung2004`, :cite:`Finlayson2015`, :cite:`Westland2004`, 

672:cite:`Wikipedia2003e` 

673""" 

674 

675 

676def polynomial_expansion( 

677 a: ArrayLike, 

678 method: ( 

679 Literal["Cheung 2004", "Finlayson 2015", "Vandermonde"] | str 

680 ) = "Cheung 2004", 

681 **kwargs: Any, 

682) -> NDArrayFloat: 

683 """ 

684 Perform polynomial expansion of the :math:`a` array. 

685 

686 Parameters 

687 ---------- 

688 a 

689 Array to expand using polynomial expansion. 

690 method 

691 Computation method for the polynomial expansion. 

692 

693 Other Parameters 

694 ---------------- 

695 degree 

696 {:func:`colour.characterisation.polynomial_expansion_Finlayson2015`, 

697 :func:`colour.characterisation.polynomial_expansion_Vandermonde`}, 

698 Expanded polynomial degree, must be one of *[1, 2, 3, 4]* for 

699 :func:`colour.characterisation.polynomial_expansion_Finlayson2015` 

700 definition. 

701 root_polynomial_expansion 

702 {:func:`colour.characterisation.polynomial_expansion_Finlayson2015`}, 

703 Whether to use the root-polynomials set for the expansion. 

704 terms 

705 {:func:`colour.characterisation.matrix_augmented_Cheung2004`}, 

706 Number of terms of the expanded polynomial. 

707 

708 Returns 

709 ------- 

710 :class:`numpy.ndarray` 

711 Polynomial-expanded :math:`a` array. 

712 

713 References 

714 ---------- 

715 :cite:`Cheung2004`, :cite:`Finlayson2015`, :cite:`Westland2004`, 

716 :cite:`Wikipedia2003e` 

717 

718 Examples 

719 -------- 

720 >>> RGB = np.array([0.17224810, 0.09170660, 0.06416938]) 

721 >>> polynomial_expansion(RGB) # doctest: +ELLIPSIS 

722 array([ 0.1722481..., 0.0917066..., 0.0641693...]) 

723 >>> polynomial_expansion(RGB, "Cheung 2004", terms=5) # doctest: +ELLIPSIS 

724 array([ 0.1722481..., 0.0917066..., 0.0641693..., 0.0010136..., 1...]) 

725 """ 

726 

727 method = validate_method(method, tuple(POLYNOMIAL_EXPANSION_METHODS)) 

728 

729 function = POLYNOMIAL_EXPANSION_METHODS[method] 

730 

731 return function(a, **filter_kwargs(function, **kwargs)) 

732 

733 

734def matrix_colour_correction_Cheung2004( 

735 M_T: ArrayLike, 

736 M_R: ArrayLike, 

737 terms: Literal[3, 4, 5, 7, 8, 10, 11, 14, 16, 17, 19, 20, 22, 35] | int = 3, 

738) -> NDArrayFloat: 

739 """ 

740 Compute a colour correction matrix from test array :math:`M_T` to 

741 reference array :math:`M_R` using the *Cheung et al. (2004)* polynomial 

742 expansion method. 

743 

744 Parameters 

745 ---------- 

746 M_T 

747 Test array :math:`M_T` to fit onto reference array :math:`M_R`. 

748 M_R 

749 Reference array that the test array :math:`M_T` will be colour 

750 fitted against. 

751 terms 

752 Number of terms of the expanded polynomial. The value must be one 

753 of the supported term counts: 3, 4, 5, 7, 8, 10, 11, 14, 16, 17, 

754 19, 20, 22, or 35. 

755 

756 Returns 

757 ------- 

758 :class:`numpy.ndarray` 

759 Colour correction matrix mapping expanded test colours to reference 

760 colours. 

761 

762 References 

763 ---------- 

764 :cite:`Cheung2004`, :cite:`Westland2004` 

765 

766 Examples 

767 -------- 

768 >>> prng = np.random.RandomState(2) 

769 >>> M_T = prng.random_sample((24, 3)) 

770 >>> M_R = M_T + (prng.random_sample((24, 3)) - 0.5) * 0.5 

771 >>> matrix_colour_correction_Cheung2004(M_T, M_R) # doctest: +ELLIPSIS 

772 array([[ 1.0526376..., 0.1378078..., -0.2276339...], 

773 [ 0.0739584..., 1.0293994..., -0.1060115...], 

774 [ 0.0572550..., -0.2052633..., 1.1015194...]]) 

775 """ 

776 

777 return least_square_mapping_MoorePenrose( 

778 matrix_augmented_Cheung2004(M_T, terms), M_R 

779 ) 

780 

781 

782def matrix_colour_correction_Finlayson2015( 

783 M_T: ArrayLike, 

784 M_R: ArrayLike, 

785 degree: Literal[1, 2, 3, 4] | int = 1, 

786 root_polynomial_expansion: bool = True, 

787) -> NDArrayFloat: 

788 """ 

789 Compute a colour correction matrix from test colour array :math:`M_T` to 

790 reference colour array :math:`M_R` using *Finlayson et al. (2015)* 

791 root-polynomial colour correction method. 

792 

793 Parameters 

794 ---------- 

795 M_T 

796 Test array :math:`M_T` to fit onto reference array :math:`M_R`. 

797 M_R 

798 Reference array the test array :math:`M_T` will be colour fitted 

799 against. 

800 degree 

801 Polynomial expansion degree for the root-polynomial basis. The value 

802 must be one of the degrees: 1, 2, 3, 4. 

803 root_polynomial_expansion 

804 Whether to use the root-polynomial basis set for the expansion. If 

805 *False*, uses standard polynomial expansion. 

806 

807 Returns 

808 ------- 

809 :class:`numpy.ndarray` 

810 Colour correction matrix mapping expanded test colours to reference 

811 colours. 

812 

813 References 

814 ---------- 

815 :cite:`Finlayson2015` 

816 

817 Examples 

818 -------- 

819 >>> prng = np.random.RandomState(2) 

820 >>> M_T = prng.random_sample((24, 3)) 

821 >>> M_R = M_T + (prng.random_sample((24, 3)) - 0.5) * 0.5 

822 >>> matrix_colour_correction_Finlayson2015(M_T, M_R) # doctest: +ELLIPSIS 

823 array([[ 1.0526376..., 0.1378078..., -0.2276339...], 

824 [ 0.0739584..., 1.0293994..., -0.1060115...], 

825 [ 0.0572550..., -0.2052633..., 1.1015194...]]) 

826 """ 

827 

828 return least_square_mapping_MoorePenrose( 

829 polynomial_expansion_Finlayson2015(M_T, degree, root_polynomial_expansion), 

830 M_R, 

831 ) 

832 

833 

834def matrix_colour_correction_Vandermonde( 

835 M_T: ArrayLike, M_R: ArrayLike, degree: int = 1 

836) -> NDArrayFloat: 

837 """ 

838 Compute a colour correction matrix from :math:`M_T` test colour array 

839 to :math:`M_R` reference colour array using the *Vandermonde* method. 

840 

841 Parameters 

842 ---------- 

843 M_T 

844 Test array :math:`M_T` to fit onto array :math:`M_R`. 

845 M_R 

846 Reference array the array :math:`M_T` will be colour fitted against. 

847 degree 

848 Expanded polynomial degree. 

849 

850 Returns 

851 ------- 

852 :class:`numpy.ndarray` 

853 Colour correction matrix mapping expanded test colours to reference 

854 colours. 

855 

856 References 

857 ---------- 

858 :cite:`Wikipedia2003e` 

859 

860 Examples 

861 -------- 

862 >>> prng = np.random.RandomState(2) 

863 >>> M_T = prng.random_sample((24, 3)) 

864 >>> M_R = M_T + (prng.random_sample((24, 3)) - 0.5) * 0.5 

865 >>> matrix_colour_correction_Vandermonde(M_T, M_R) # doctest: +ELLIPSIS 

866 array([[ 1.0300256..., 0.1141770..., -0.2621816..., 0.0418022...], 

867 [ 0.0670209..., 1.0221494..., -0.1166108..., 0.0128250...], 

868 [ 0.0744612..., -0.1872819..., 1.1278078..., -0.0318085...]]) 

869 """ 

870 

871 return least_square_mapping_MoorePenrose( 

872 polynomial_expansion_Vandermonde(M_T, degree), M_R 

873 ) 

874 

875 

876MATRIX_COLOUR_CORRECTION_METHODS: CanonicalMapping = CanonicalMapping( 

877 { 

878 "Cheung 2004": matrix_colour_correction_Cheung2004, 

879 "Finlayson 2015": matrix_colour_correction_Finlayson2015, 

880 "Vandermonde": matrix_colour_correction_Vandermonde, 

881 } 

882) 

883MATRIX_COLOUR_CORRECTION_METHODS.__doc__ = """ 

884Supported colour correction matrix computation methods. 

885 

886References 

887---------- 

888:cite:`Cheung2004`, :cite:`Finlayson2015`, :cite:`Westland2004`, 

889:cite:`Wikipedia2003e` 

890""" 

891 

892 

893def matrix_colour_correction( 

894 M_T: ArrayLike, 

895 M_R: ArrayLike, 

896 method: ( 

897 Literal["Cheung 2004", "Finlayson 2015", "Vandermonde"] | str 

898 ) = "Cheung 2004", 

899 **kwargs: Any, 

900) -> NDArrayFloat: 

901 """ 

902 Compute a colour correction matrix from :math:`M_T` colour array to 

903 :math:`M_R` colour array. 

904 

905 Compute the colour correction matrix using multiple linear or polynomial 

906 regression with the specified method. The resulting matrix enables colour 

907 matching between two arrays, such as matching two *ColorChecker* colour 

908 rendition charts together. 

909 

910 Parameters 

911 ---------- 

912 M_T 

913 Test array :math:`M_T` to fit onto array :math:`M_R`. 

914 M_R 

915 Reference array the array :math:`M_T` will be colour fitted against. 

916 method 

917 Computation method. 

918 

919 Other Parameters 

920 ---------------- 

921 degree 

922 {:func:`colour.characterisation.matrix_colour_correction_Finlayson2015`, 

923 :func:`colour.characterisation.matrix_colour_correction_Vandermonde`}, 

924 Expanded polynomial degree, must be one of *[1, 2, 3, 4]* for 

925 :func:`colour.characterisation.matrix_colour_correction_Finlayson2015` 

926 definition. 

927 root_polynomial_expansion 

928 {:func:`colour.characterisation.matrix_colour_correction_Finlayson2015`}, 

929 Whether to use the root-polynomials set for the expansion. 

930 terms 

931 {:func:`colour.characterisation.matrix_colour_correction_Cheung2004`}, 

932 Number of terms of the expanded polynomial. 

933 

934 Returns 

935 ------- 

936 :class:`numpy.ndarray` 

937 Colour correction matrix mapping expanded test colours to reference 

938 colours. 

939 

940 References 

941 ---------- 

942 :cite:`Cheung2004`, :cite:`Finlayson2015`, :cite:`Westland2004`, 

943 :cite:`Wikipedia2003e` 

944 

945 Examples 

946 -------- 

947 >>> M_T = np.array( 

948 ... [ 

949 ... [0.17224810, 0.09170660, 0.06416938], 

950 ... [0.49189645, 0.27802050, 0.21923399], 

951 ... [0.10999751, 0.18658946, 0.29938611], 

952 ... [0.11666120, 0.14327905, 0.05713804], 

953 ... [0.18988879, 0.18227649, 0.36056247], 

954 ... [0.12501329, 0.42223442, 0.37027445], 

955 ... [0.64785606, 0.22396782, 0.03365194], 

956 ... [0.06761093, 0.11076896, 0.39779139], 

957 ... [0.49101797, 0.09448929, 0.11623839], 

958 ... [0.11622386, 0.04425753, 0.14469986], 

959 ... [0.36867946, 0.44545230, 0.06028681], 

960 ... [0.61632937, 0.32323906, 0.02437089], 

961 ... [0.03016472, 0.06153243, 0.29014596], 

962 ... [0.11103655, 0.30553067, 0.08149137], 

963 ... [0.41162190, 0.05816656, 0.04845934], 

964 ... [0.73339206, 0.53075188, 0.02475212], 

965 ... [0.47347718, 0.08834792, 0.30310315], 

966 ... [0.00000000, 0.25187016, 0.35062450], 

967 ... [0.76809639, 0.78486240, 0.77808297], 

968 ... [0.53822392, 0.54307997, 0.54710883], 

969 ... [0.35458526, 0.35318419, 0.35524431], 

970 ... [0.17976704, 0.18000531, 0.17991488], 

971 ... [0.09351417, 0.09510603, 0.09675027], 

972 ... [0.03405071, 0.03295077, 0.03702047], 

973 ... ] 

974 ... ) 

975 >>> M_R = np.array( 

976 ... [ 

977 ... [0.15579559, 0.09715755, 0.07514556], 

978 ... [0.39113140, 0.25943419, 0.21266708], 

979 ... [0.12824821, 0.18463570, 0.31508023], 

980 ... [0.12028974, 0.13455659, 0.07408400], 

981 ... [0.19368988, 0.21158946, 0.37955964], 

982 ... [0.19957425, 0.36085439, 0.40678123], 

983 ... [0.48896605, 0.20691688, 0.05816533], 

984 ... [0.09775522, 0.16710693, 0.47147724], 

985 ... [0.39358649, 0.12233400, 0.10526425], 

986 ... [0.10780332, 0.07258529, 0.16151473], 

987 ... [0.27502671, 0.34705454, 0.09728099], 

988 ... [0.43980441, 0.26880559, 0.05430533], 

989 ... [0.05887212, 0.11126272, 0.38552469], 

990 ... [0.12705825, 0.25787860, 0.13566464], 

991 ... [0.35612929, 0.07933258, 0.05118732], 

992 ... [0.48131976, 0.42082843, 0.07120612], 

993 ... [0.34665585, 0.15170714, 0.24969804], 

994 ... [0.08261116, 0.24588716, 0.48707733], 

995 ... [0.66054904, 0.65941137, 0.66376412], 

996 ... [0.48051509, 0.47870296, 0.48230082], 

997 ... [0.33045354, 0.32904184, 0.33228886], 

998 ... [0.18001305, 0.17978567, 0.18004416], 

999 ... [0.10283975, 0.10424680, 0.10384975], 

1000 ... [0.04742204, 0.04772203, 0.04914226], 

1001 ... ] 

1002 ... ) 

1003 >>> matrix_colour_correction(M_T, M_R) # doctest: +ELLIPSIS 

1004 array([[ 0.6982266..., 0.0307162..., 0.1621042...], 

1005 [ 0.0689349..., 0.6757961..., 0.1643038...], 

1006 [-0.0631495..., 0.0921247..., 0.9713415...]]) 

1007 """ 

1008 

1009 method = validate_method(method, tuple(MATRIX_COLOUR_CORRECTION_METHODS))