Hide keyboard shortcuts

Hot-keys on this page

r m x p   toggle line displays

j k   next/prev highlighted chunk

0   (zero) top of page

1   (one) first highlighted chunk

1""" 

2Real spectrum transforms (DCT, DST, MDCT) 

3""" 

4 

5__all__ = ['dct', 'idct', 'dst', 'idst', 'dctn', 'idctn', 'dstn', 'idstn'] 

6 

7from scipy.fft import _pocketfft 

8from .helper import _good_shape 

9 

10_inverse_typemap = {1: 1, 2: 3, 3: 2, 4: 4} 

11 

12 

13def dctn(x, type=2, shape=None, axes=None, norm=None, overwrite_x=False): 

14 """ 

15 Return multidimensional Discrete Cosine Transform along the specified axes. 

16 

17 Parameters 

18 ---------- 

19 x : array_like 

20 The input array. 

21 type : {1, 2, 3, 4}, optional 

22 Type of the DCT (see Notes). Default type is 2. 

23 shape : int or array_like of ints or None, optional 

24 The shape of the result. If both `shape` and `axes` (see below) are 

25 None, `shape` is ``x.shape``; if `shape` is None but `axes` is 

26 not None, then `shape` is ``scipy.take(x.shape, axes, axis=0)``. 

27 If ``shape[i] > x.shape[i]``, the ith dimension is padded with zeros. 

28 If ``shape[i] < x.shape[i]``, the ith dimension is truncated to 

29 length ``shape[i]``. 

30 If any element of `shape` is -1, the size of the corresponding 

31 dimension of `x` is used. 

32 axes : int or array_like of ints or None, optional 

33 Axes along which the DCT is computed. 

34 The default is over all axes. 

35 norm : {None, 'ortho'}, optional 

36 Normalization mode (see Notes). Default is None. 

37 overwrite_x : bool, optional 

38 If True, the contents of `x` can be destroyed; the default is False. 

39 

40 Returns 

41 ------- 

42 y : ndarray of real 

43 The transformed input array. 

44 

45 See Also 

46 -------- 

47 idctn : Inverse multidimensional DCT 

48 

49 Notes 

50 ----- 

51 For full details of the DCT types and normalization modes, as well as 

52 references, see `dct`. 

53 

54 Examples 

55 -------- 

56 >>> from scipy.fftpack import dctn, idctn 

57 >>> y = np.random.randn(16, 16) 

58 >>> np.allclose(y, idctn(dctn(y, norm='ortho'), norm='ortho')) 

59 True 

60 

61 """ 

62 shape = _good_shape(x, shape, axes) 

63 return _pocketfft.dctn(x, type, shape, axes, norm, overwrite_x) 

64 

65 

66def idctn(x, type=2, shape=None, axes=None, norm=None, overwrite_x=False): 

67 """ 

68 Return multidimensional Discrete Cosine Transform along the specified axes. 

69 

70 Parameters 

71 ---------- 

72 x : array_like 

73 The input array. 

74 type : {1, 2, 3, 4}, optional 

75 Type of the DCT (see Notes). Default type is 2. 

76 shape : int or array_like of ints or None, optional 

77 The shape of the result. If both `shape` and `axes` (see below) are 

78 None, `shape` is ``x.shape``; if `shape` is None but `axes` is 

79 not None, then `shape` is ``scipy.take(x.shape, axes, axis=0)``. 

80 If ``shape[i] > x.shape[i]``, the ith dimension is padded with zeros. 

81 If ``shape[i] < x.shape[i]``, the ith dimension is truncated to 

82 length ``shape[i]``. 

83 If any element of `shape` is -1, the size of the corresponding 

84 dimension of `x` is used. 

85 axes : int or array_like of ints or None, optional 

86 Axes along which the IDCT is computed. 

87 The default is over all axes. 

88 norm : {None, 'ortho'}, optional 

89 Normalization mode (see Notes). Default is None. 

90 overwrite_x : bool, optional 

91 If True, the contents of `x` can be destroyed; the default is False. 

92 

93 Returns 

94 ------- 

95 y : ndarray of real 

96 The transformed input array. 

97 

98 See Also 

99 -------- 

100 dctn : multidimensional DCT 

101 

102 Notes 

103 ----- 

104 For full details of the IDCT types and normalization modes, as well as 

105 references, see `idct`. 

106 

107 Examples 

108 -------- 

109 >>> from scipy.fftpack import dctn, idctn 

110 >>> y = np.random.randn(16, 16) 

111 >>> np.allclose(y, idctn(dctn(y, norm='ortho'), norm='ortho')) 

112 True 

113 

114 """ 

115 type = _inverse_typemap[type] 

116 shape = _good_shape(x, shape, axes) 

117 return _pocketfft.dctn(x, type, shape, axes, norm, overwrite_x) 

118 

119 

120def dstn(x, type=2, shape=None, axes=None, norm=None, overwrite_x=False): 

121 """ 

122 Return multidimensional Discrete Sine Transform along the specified axes. 

123 

124 Parameters 

125 ---------- 

126 x : array_like 

127 The input array. 

128 type : {1, 2, 3, 4}, optional 

129 Type of the DST (see Notes). Default type is 2. 

130 shape : int or array_like of ints or None, optional 

131 The shape of the result. If both `shape` and `axes` (see below) are 

132 None, `shape` is ``x.shape``; if `shape` is None but `axes` is 

133 not None, then `shape` is ``scipy.take(x.shape, axes, axis=0)``. 

134 If ``shape[i] > x.shape[i]``, the ith dimension is padded with zeros. 

135 If ``shape[i] < x.shape[i]``, the ith dimension is truncated to 

136 length ``shape[i]``. 

137 If any element of `shape` is -1, the size of the corresponding 

138 dimension of `x` is used. 

139 axes : int or array_like of ints or None, optional 

140 Axes along which the DCT is computed. 

141 The default is over all axes. 

142 norm : {None, 'ortho'}, optional 

143 Normalization mode (see Notes). Default is None. 

144 overwrite_x : bool, optional 

145 If True, the contents of `x` can be destroyed; the default is False. 

146 

147 Returns 

148 ------- 

149 y : ndarray of real 

150 The transformed input array. 

151 

152 See Also 

153 -------- 

154 idstn : Inverse multidimensional DST 

155 

156 Notes 

157 ----- 

158 For full details of the DST types and normalization modes, as well as 

159 references, see `dst`. 

160 

161 Examples 

162 -------- 

163 >>> from scipy.fftpack import dstn, idstn 

164 >>> y = np.random.randn(16, 16) 

165 >>> np.allclose(y, idstn(dstn(y, norm='ortho'), norm='ortho')) 

166 True 

167 

168 """ 

169 shape = _good_shape(x, shape, axes) 

170 return _pocketfft.dstn(x, type, shape, axes, norm, overwrite_x) 

171 

172 

173def idstn(x, type=2, shape=None, axes=None, norm=None, overwrite_x=False): 

174 """ 

175 Return multidimensional Discrete Sine Transform along the specified axes. 

176 

177 Parameters 

178 ---------- 

179 x : array_like 

180 The input array. 

181 type : {1, 2, 3, 4}, optional 

182 Type of the DST (see Notes). Default type is 2. 

183 shape : int or array_like of ints or None, optional 

184 The shape of the result. If both `shape` and `axes` (see below) are 

185 None, `shape` is ``x.shape``; if `shape` is None but `axes` is 

186 not None, then `shape` is ``scipy.take(x.shape, axes, axis=0)``. 

187 If ``shape[i] > x.shape[i]``, the ith dimension is padded with zeros. 

188 If ``shape[i] < x.shape[i]``, the ith dimension is truncated to 

189 length ``shape[i]``. 

190 If any element of `shape` is -1, the size of the corresponding 

191 dimension of `x` is used. 

192 axes : int or array_like of ints or None, optional 

193 Axes along which the IDST is computed. 

194 The default is over all axes. 

195 norm : {None, 'ortho'}, optional 

196 Normalization mode (see Notes). Default is None. 

197 overwrite_x : bool, optional 

198 If True, the contents of `x` can be destroyed; the default is False. 

199 

200 Returns 

201 ------- 

202 y : ndarray of real 

203 The transformed input array. 

204 

205 See Also 

206 -------- 

207 dstn : multidimensional DST 

208 

209 Notes 

210 ----- 

211 For full details of the IDST types and normalization modes, as well as 

212 references, see `idst`. 

213 

214 Examples 

215 -------- 

216 >>> from scipy.fftpack import dstn, idstn 

217 >>> y = np.random.randn(16, 16) 

218 >>> np.allclose(y, idstn(dstn(y, norm='ortho'), norm='ortho')) 

219 True 

220 

221 """ 

222 type = _inverse_typemap[type] 

223 shape = _good_shape(x, shape, axes) 

224 return _pocketfft.dstn(x, type, shape, axes, norm, overwrite_x) 

225 

226 

227def dct(x, type=2, n=None, axis=-1, norm=None, overwrite_x=False): 

228 r""" 

229 Return the Discrete Cosine Transform of arbitrary type sequence x. 

230 

231 Parameters 

232 ---------- 

233 x : array_like 

234 The input array. 

235 type : {1, 2, 3, 4}, optional 

236 Type of the DCT (see Notes). Default type is 2. 

237 n : int, optional 

238 Length of the transform. If ``n < x.shape[axis]``, `x` is 

239 truncated. If ``n > x.shape[axis]``, `x` is zero-padded. The 

240 default results in ``n = x.shape[axis]``. 

241 axis : int, optional 

242 Axis along which the dct is computed; the default is over the 

243 last axis (i.e., ``axis=-1``). 

244 norm : {None, 'ortho'}, optional 

245 Normalization mode (see Notes). Default is None. 

246 overwrite_x : bool, optional 

247 If True, the contents of `x` can be destroyed; the default is False. 

248 

249 Returns 

250 ------- 

251 y : ndarray of real 

252 The transformed input array. 

253 

254 See Also 

255 -------- 

256 idct : Inverse DCT 

257 

258 Notes 

259 ----- 

260 For a single dimension array ``x``, ``dct(x, norm='ortho')`` is equal to 

261 MATLAB ``dct(x)``. 

262 

263 There are, theoretically, 8 types of the DCT, only the first 4 types are 

264 implemented in scipy. 'The' DCT generally refers to DCT type 2, and 'the' 

265 Inverse DCT generally refers to DCT type 3. 

266 

267 **Type I** 

268 

269 There are several definitions of the DCT-I; we use the following 

270 (for ``norm=None``) 

271 

272 .. math:: 

273 

274 y_k = x_0 + (-1)^k x_{N-1} + 2 \sum_{n=1}^{N-2} x_n \cos\left( 

275 \frac{\pi k n}{N-1} \right) 

276 

277 If ``norm='ortho'``, ``x[0]`` and ``x[N-1]`` are multiplied by a scaling 

278 factor of :math:`\sqrt{2}`, and ``y[k]`` is multiplied by a scaling factor 

279 ``f`` 

280 

281 .. math:: 

282 

283 f = \begin{cases} 

284 \frac{1}{2}\sqrt{\frac{1}{N-1}} & \text{if }k=0\text{ or }N-1, \\ 

285 \frac{1}{2}\sqrt{\frac{2}{N-1}} & \text{otherwise} \end{cases} 

286 

287 .. versionadded:: 1.2.0 

288 Orthonormalization in DCT-I. 

289 

290 .. note:: 

291 The DCT-I is only supported for input size > 1. 

292 

293 **Type II** 

294 

295 There are several definitions of the DCT-II; we use the following 

296 (for ``norm=None``) 

297 

298 .. math:: 

299 

300 y_k = 2 \sum_{n=0}^{N-1} x_n \cos\left(\frac{\pi k(2n+1)}{2N} \right) 

301 

302 If ``norm='ortho'``, ``y[k]`` is multiplied by a scaling factor ``f`` 

303 

304 .. math:: 

305 f = \begin{cases} 

306 \sqrt{\frac{1}{4N}} & \text{if }k=0, \\ 

307 \sqrt{\frac{1}{2N}} & \text{otherwise} \end{cases} 

308 

309 which makes the corresponding matrix of coefficients orthonormal 

310 (``O @ O.T = np.eye(N)``). 

311 

312 **Type III** 

313 

314 There are several definitions, we use the following (for ``norm=None``) 

315 

316 .. math:: 

317 

318 y_k = x_0 + 2 \sum_{n=1}^{N-1} x_n \cos\left(\frac{\pi(2k+1)n}{2N}\right) 

319 

320 or, for ``norm='ortho'`` 

321 

322 .. math:: 

323 

324 y_k = \frac{x_0}{\sqrt{N}} + \sqrt{\frac{2}{N}} \sum_{n=1}^{N-1} x_n 

325 \cos\left(\frac{\pi(2k+1)n}{2N}\right) 

326 

327 The (unnormalized) DCT-III is the inverse of the (unnormalized) DCT-II, up 

328 to a factor `2N`. The orthonormalized DCT-III is exactly the inverse of 

329 the orthonormalized DCT-II. 

330 

331 **Type IV** 

332 

333 There are several definitions of the DCT-IV; we use the following 

334 (for ``norm=None``) 

335 

336 .. math:: 

337 

338 y_k = 2 \sum_{n=0}^{N-1} x_n \cos\left(\frac{\pi(2k+1)(2n+1)}{4N} \right) 

339 

340 If ``norm='ortho'``, ``y[k]`` is multiplied by a scaling factor ``f`` 

341 

342 .. math:: 

343 

344 f = \frac{1}{\sqrt{2N}} 

345 

346 .. versionadded:: 1.2.0 

347 Support for DCT-IV. 

348 

349 References 

350 ---------- 

351 .. [1] 'A Fast Cosine Transform in One and Two Dimensions', by J. 

352 Makhoul, `IEEE Transactions on acoustics, speech and signal 

353 processing` vol. 28(1), pp. 27-34, 

354 :doi:`10.1109/TASSP.1980.1163351` (1980). 

355 .. [2] Wikipedia, "Discrete cosine transform", 

356 https://en.wikipedia.org/wiki/Discrete_cosine_transform 

357 

358 Examples 

359 -------- 

360 The Type 1 DCT is equivalent to the FFT (though faster) for real, 

361 even-symmetrical inputs. The output is also real and even-symmetrical. 

362 Half of the FFT input is used to generate half of the FFT output: 

363 

364 >>> from scipy.fftpack import fft, dct 

365 >>> fft(np.array([4., 3., 5., 10., 5., 3.])).real 

366 array([ 30., -8., 6., -2., 6., -8.]) 

367 >>> dct(np.array([4., 3., 5., 10.]), 1) 

368 array([ 30., -8., 6., -2.]) 

369 

370 """ 

371 return _pocketfft.dct(x, type, n, axis, norm, overwrite_x) 

372 

373 

374def idct(x, type=2, n=None, axis=-1, norm=None, overwrite_x=False): 

375 """ 

376 Return the Inverse Discrete Cosine Transform of an arbitrary type sequence. 

377 

378 Parameters 

379 ---------- 

380 x : array_like 

381 The input array. 

382 type : {1, 2, 3, 4}, optional 

383 Type of the DCT (see Notes). Default type is 2. 

384 n : int, optional 

385 Length of the transform. If ``n < x.shape[axis]``, `x` is 

386 truncated. If ``n > x.shape[axis]``, `x` is zero-padded. The 

387 default results in ``n = x.shape[axis]``. 

388 axis : int, optional 

389 Axis along which the idct is computed; the default is over the 

390 last axis (i.e., ``axis=-1``). 

391 norm : {None, 'ortho'}, optional 

392 Normalization mode (see Notes). Default is None. 

393 overwrite_x : bool, optional 

394 If True, the contents of `x` can be destroyed; the default is False. 

395 

396 Returns 

397 ------- 

398 idct : ndarray of real 

399 The transformed input array. 

400 

401 See Also 

402 -------- 

403 dct : Forward DCT 

404 

405 Notes 

406 ----- 

407 For a single dimension array `x`, ``idct(x, norm='ortho')`` is equal to 

408 MATLAB ``idct(x)``. 

409 

410 'The' IDCT is the IDCT of type 2, which is the same as DCT of type 3. 

411 

412 IDCT of type 1 is the DCT of type 1, IDCT of type 2 is the DCT of type 

413 3, and IDCT of type 3 is the DCT of type 2. IDCT of type 4 is the DCT 

414 of type 4. For the definition of these types, see `dct`. 

415 

416 Examples 

417 -------- 

418 The Type 1 DCT is equivalent to the DFT for real, even-symmetrical 

419 inputs. The output is also real and even-symmetrical. Half of the IFFT 

420 input is used to generate half of the IFFT output: 

421 

422 >>> from scipy.fftpack import ifft, idct 

423 >>> ifft(np.array([ 30., -8., 6., -2., 6., -8.])).real 

424 array([ 4., 3., 5., 10., 5., 3.]) 

425 >>> idct(np.array([ 30., -8., 6., -2.]), 1) / 6 

426 array([ 4., 3., 5., 10.]) 

427 

428 """ 

429 type = _inverse_typemap[type] 

430 return _pocketfft.dct(x, type, n, axis, norm, overwrite_x) 

431 

432 

433def dst(x, type=2, n=None, axis=-1, norm=None, overwrite_x=False): 

434 r""" 

435 Return the Discrete Sine Transform of arbitrary type sequence x. 

436 

437 Parameters 

438 ---------- 

439 x : array_like 

440 The input array. 

441 type : {1, 2, 3, 4}, optional 

442 Type of the DST (see Notes). Default type is 2. 

443 n : int, optional 

444 Length of the transform. If ``n < x.shape[axis]``, `x` is 

445 truncated. If ``n > x.shape[axis]``, `x` is zero-padded. The 

446 default results in ``n = x.shape[axis]``. 

447 axis : int, optional 

448 Axis along which the dst is computed; the default is over the 

449 last axis (i.e., ``axis=-1``). 

450 norm : {None, 'ortho'}, optional 

451 Normalization mode (see Notes). Default is None. 

452 overwrite_x : bool, optional 

453 If True, the contents of `x` can be destroyed; the default is False. 

454 

455 Returns 

456 ------- 

457 dst : ndarray of reals 

458 The transformed input array. 

459 

460 See Also 

461 -------- 

462 idst : Inverse DST 

463 

464 Notes 

465 ----- 

466 For a single dimension array ``x``. 

467 

468 There are, theoretically, 8 types of the DST for different combinations of 

469 even/odd boundary conditions and boundary off sets [1]_, only the first 

470 4 types are implemented in scipy. 

471 

472 **Type I** 

473 

474 There are several definitions of the DST-I; we use the following 

475 for ``norm=None``. DST-I assumes the input is odd around `n=-1` and `n=N`. 

476 

477 .. math:: 

478 

479 y_k = 2 \sum_{n=0}^{N-1} x_n \sin\left(\frac{\pi(k+1)(n+1)}{N+1}\right) 

480 

481 Note that the DST-I is only supported for input size > 1. 

482 The (unnormalized) DST-I is its own inverse, up to a factor `2(N+1)`. 

483 The orthonormalized DST-I is exactly its own inverse. 

484 

485 **Type II** 

486 

487 There are several definitions of the DST-II; we use the following for 

488 ``norm=None``. DST-II assumes the input is odd around `n=-1/2` and 

489 `n=N-1/2`; the output is odd around :math:`k=-1` and even around `k=N-1` 

490 

491 .. math:: 

492 

493 y_k = 2 \sum_{n=0}^{N-1} x_n \sin\left(\frac{\pi(k+1)(2n+1)}{2N}\right) 

494 

495 if ``norm='ortho'``, ``y[k]`` is multiplied by a scaling factor ``f`` 

496 

497 .. math:: 

498 

499 f = \begin{cases} 

500 \sqrt{\frac{1}{4N}} & \text{if }k = 0, \\ 

501 \sqrt{\frac{1}{2N}} & \text{otherwise} \end{cases} 

502 

503 **Type III** 

504 

505 There are several definitions of the DST-III, we use the following (for 

506 ``norm=None``). DST-III assumes the input is odd around `n=-1` and even 

507 around `n=N-1` 

508 

509 .. math:: 

510 

511 y_k = (-1)^k x_{N-1} + 2 \sum_{n=0}^{N-2} x_n \sin\left( 

512 \frac{\pi(2k+1)(n+1)}{2N}\right) 

513 

514 The (unnormalized) DST-III is the inverse of the (unnormalized) DST-II, up 

515 to a factor `2N`. The orthonormalized DST-III is exactly the inverse of the 

516 orthonormalized DST-II. 

517 

518 .. versionadded:: 0.11.0 

519 

520 **Type IV** 

521 

522 There are several definitions of the DST-IV, we use the following (for 

523 ``norm=None``). DST-IV assumes the input is odd around `n=-0.5` and even 

524 around `n=N-0.5` 

525 

526 .. math:: 

527 

528 y_k = 2 \sum_{n=0}^{N-1} x_n \sin\left(\frac{\pi(2k+1)(2n+1)}{4N}\right) 

529 

530 The (unnormalized) DST-IV is its own inverse, up to a factor `2N`. The 

531 orthonormalized DST-IV is exactly its own inverse. 

532 

533 .. versionadded:: 1.2.0 

534 Support for DST-IV. 

535 

536 References 

537 ---------- 

538 .. [1] Wikipedia, "Discrete sine transform", 

539 https://en.wikipedia.org/wiki/Discrete_sine_transform 

540 

541 """ 

542 return _pocketfft.dst(x, type, n, axis, norm, overwrite_x) 

543 

544 

545def idst(x, type=2, n=None, axis=-1, norm=None, overwrite_x=False): 

546 """ 

547 Return the Inverse Discrete Sine Transform of an arbitrary type sequence. 

548 

549 Parameters 

550 ---------- 

551 x : array_like 

552 The input array. 

553 type : {1, 2, 3, 4}, optional 

554 Type of the DST (see Notes). Default type is 2. 

555 n : int, optional 

556 Length of the transform. If ``n < x.shape[axis]``, `x` is 

557 truncated. If ``n > x.shape[axis]``, `x` is zero-padded. The 

558 default results in ``n = x.shape[axis]``. 

559 axis : int, optional 

560 Axis along which the idst is computed; the default is over the 

561 last axis (i.e., ``axis=-1``). 

562 norm : {None, 'ortho'}, optional 

563 Normalization mode (see Notes). Default is None. 

564 overwrite_x : bool, optional 

565 If True, the contents of `x` can be destroyed; the default is False. 

566 

567 Returns 

568 ------- 

569 idst : ndarray of real 

570 The transformed input array. 

571 

572 See Also 

573 -------- 

574 dst : Forward DST 

575 

576 Notes 

577 ----- 

578 'The' IDST is the IDST of type 2, which is the same as DST of type 3. 

579 

580 IDST of type 1 is the DST of type 1, IDST of type 2 is the DST of type 

581 3, and IDST of type 3 is the DST of type 2. For the definition of these 

582 types, see `dst`. 

583 

584 .. versionadded:: 0.11.0 

585 

586 """ 

587 type = _inverse_typemap[type] 

588 return _pocketfft.dst(x, type, n, axis, norm, overwrite_x)