You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

233 lines
5.1 KiB

3 years ago
  1. <?php
  2. /**
  3. * @copyright Copyright (c) 2016, ownCloud, Inc.
  4. *
  5. * @author Joas Schilling <coding@schilljs.com>
  6. * @author Morris Jobke <hey@morrisjobke.de>
  7. * @author Olivier Paroz <github@oparoz.com>
  8. * @author Robin Appelman <robin@icewind.nl>
  9. * @author Roeland Jago Douma <roeland@famdouma.nl>
  10. *
  11. * @license AGPL-3.0
  12. *
  13. * This code is free software: you can redistribute it and/or modify
  14. * it under the terms of the GNU Affero General Public License, version 3,
  15. * as published by the Free Software Foundation.
  16. *
  17. * This program is distributed in the hope that it will be useful,
  18. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  20. * GNU Affero General Public License for more details.
  21. *
  22. * You should have received a copy of the GNU Affero General Public License, version 3,
  23. * along with this program. If not, see <http://www.gnu.org/licenses/>
  24. *
  25. */
  26. namespace OCP;
  27. /**
  28. * Class for basic image manipulation
  29. * @since 8.1.0
  30. */
  31. interface IImage {
  32. /**
  33. * Determine whether the object contains an image resource.
  34. *
  35. * @return bool
  36. * @since 8.1.0
  37. */
  38. public function valid();
  39. /**
  40. * Returns the MIME type of the image or an empty string if no image is loaded.
  41. *
  42. * @return string
  43. * @since 8.1.0
  44. */
  45. public function mimeType();
  46. /**
  47. * Returns the width of the image or -1 if no image is loaded.
  48. *
  49. * @return int
  50. * @since 8.1.0
  51. */
  52. public function width();
  53. /**
  54. * Returns the height of the image or -1 if no image is loaded.
  55. *
  56. * @return int
  57. * @since 8.1.0
  58. */
  59. public function height();
  60. /**
  61. * Returns the width when the image orientation is top-left.
  62. *
  63. * @return int
  64. * @since 8.1.0
  65. */
  66. public function widthTopLeft();
  67. /**
  68. * Returns the height when the image orientation is top-left.
  69. *
  70. * @return int
  71. * @since 8.1.0
  72. */
  73. public function heightTopLeft();
  74. /**
  75. * Outputs the image.
  76. *
  77. * @param string $mimeType
  78. * @return bool
  79. * @since 8.1.0
  80. */
  81. public function show($mimeType = null);
  82. /**
  83. * Saves the image.
  84. *
  85. * @param string $filePath
  86. * @param string $mimeType
  87. * @return bool
  88. * @since 8.1.0
  89. */
  90. public function save($filePath = null, $mimeType = null);
  91. /**
  92. * @return resource Returns the image resource in any.
  93. * @since 8.1.0
  94. */
  95. public function resource();
  96. /**
  97. * @return string Returns the raw data mimetype
  98. * @since 13.0.0
  99. */
  100. public function dataMimeType();
  101. /**
  102. * @return string Returns the raw image data.
  103. * @since 8.1.0
  104. */
  105. public function data();
  106. /**
  107. * (I'm open for suggestions on better method name ;)
  108. * Get the orientation based on EXIF data.
  109. *
  110. * @return int The orientation or -1 if no EXIF data is available.
  111. * @since 8.1.0
  112. */
  113. public function getOrientation();
  114. /**
  115. * (I'm open for suggestions on better method name ;)
  116. * Fixes orientation based on EXIF data.
  117. *
  118. * @return bool
  119. * @since 8.1.0
  120. */
  121. public function fixOrientation();
  122. /**
  123. * Resizes the image preserving ratio.
  124. *
  125. * @param integer $maxSize The maximum size of either the width or height.
  126. * @return bool
  127. * @since 8.1.0
  128. */
  129. public function resize($maxSize);
  130. /**
  131. * @param int $width
  132. * @param int $height
  133. * @return bool
  134. * @since 8.1.0
  135. */
  136. public function preciseResize(int $width, int $height): bool;
  137. /**
  138. * Crops the image to the middle square. If the image is already square it just returns.
  139. *
  140. * @param int $size maximum size for the result (optional)
  141. * @return bool for success or failure
  142. * @since 8.1.0
  143. */
  144. public function centerCrop($size = 0);
  145. /**
  146. * Crops the image from point $x$y with dimension $wx$h.
  147. *
  148. * @param int $x Horizontal position
  149. * @param int $y Vertical position
  150. * @param int $w Width
  151. * @param int $h Height
  152. * @return bool for success or failure
  153. * @since 8.1.0
  154. */
  155. public function crop(int $x, int $y, int $w, int $h): bool;
  156. /**
  157. * Resizes the image to fit within a boundary while preserving ratio.
  158. *
  159. * @param integer $maxWidth
  160. * @param integer $maxHeight
  161. * @return bool
  162. * @since 8.1.0
  163. */
  164. public function fitIn($maxWidth, $maxHeight);
  165. /**
  166. * Shrinks the image to fit within a boundary while preserving ratio.
  167. *
  168. * @param integer $maxWidth
  169. * @param integer $maxHeight
  170. * @return bool
  171. * @since 8.1.0
  172. */
  173. public function scaleDownToFit($maxWidth, $maxHeight);
  174. /**
  175. * create a copy of this image
  176. *
  177. * @return IImage
  178. * @since 19.0.0
  179. */
  180. public function copy(): IImage;
  181. /**
  182. * create a new cropped copy of this image
  183. *
  184. * @param int $x Horizontal position
  185. * @param int $y Vertical position
  186. * @param int $w Width
  187. * @param int $h Height
  188. * @return IImage
  189. * @since 19.0.0
  190. */
  191. public function cropCopy(int $x, int $y, int $w, int $h): IImage;
  192. /**
  193. * create a new resized copy of this image
  194. *
  195. * @param int $width
  196. * @param int $height
  197. * @return IImage
  198. * @since 19.0.0
  199. */
  200. public function preciseResizeCopy(int $width, int $height): IImage;
  201. /**
  202. * create a new resized copy of this image
  203. *
  204. * @param integer $maxSize The maximum size of either the width or height.
  205. * @return IImage
  206. * @since 19.0.0
  207. */
  208. public function resizeCopy(int $maxSize): IImage;
  209. }