001/*
002 * (C) Copyright 2007-2019 Nuxeo (http://nuxeo.com/) and others.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 *
016 * Contributors:
017 *     Nuxeo - initial API and implementation
018 *
019 * $Id$
020 */
021package org.nuxeo.ecm.platform.picture.api;
022
023import java.io.File;
024import java.io.IOException;
025import java.util.List;
026import java.util.Map;
027
028import org.nuxeo.ecm.core.api.Blob;
029import org.nuxeo.ecm.core.api.DocumentModel;
030
031/**
032 * @author Max Stepanov
033 */
034public interface ImagingService {
035
036    /**
037     * Returns the registered picture conversions.
038     *
039     * @since 7.1
040     */
041    List<PictureConversion> getPictureConversions();
042
043    /**
044     * Returns a {@link org.nuxeo.ecm.platform.picture.api.PictureConversion} given its {@code id}.
045     *
046     * @since 7.1
047     */
048    PictureConversion getPictureConversion(String id);
049
050    /**
051     * Crops an image.
052     */
053    Blob crop(Blob blob, int x, int y, int width, int height);
054
055    /**
056     * Resizes image.
057     */
058    Blob resize(Blob blob, String finalFormat, int width, int height, int depth);
059
060    /**
061     * Rotates an image.
062     *
063     * @param blob a Blob containing the image
064     * @param angle the angle of the rotation
065     * @return a Blob holding the rotated image
066     */
067    Blob rotate(Blob blob, int angle);
068
069    /**
070     * Converts an image to PDF.
071     *
072     * @param blob a Blob containing the image
073     * @return a Blob holding the resulting PDF
074     *
075     * @since 8.4
076     */
077    Blob convertToPDF(Blob blob);
078
079    /**
080     * Retrieves metadata from an image contained in a {@link Blob}.
081     *
082     * @return the image metadata as a map String -&gt; Object
083     * @deprecated since 7.2. Please use instead
084     * {@code org.nuxeo.binary.metadata.api.BinaryMetadataService#readMetadata(Blob, boolean)}
085     */
086    @Deprecated
087    Map<String, Object> getImageMetadata(Blob blob);
088
089    /**
090     * Returns the mime-type for the given file.
091     */
092    String getImageMimeType(File file);
093
094    /**
095     * Returns the mime-type for the given Blob
096     *
097     * @since 5.7
098     */
099    String getImageMimeType(Blob blob);
100
101    /**
102     * Retrieves the {@link ImageInfo} of the {@link Blob} that is received as parameter.
103     * <p>
104     * The information provided by the <b>ImageInfo</b>, like width, height or format, is obtained using ImageMagick
105     * (see http://www.imagemagick.org/script/index.php for more details on ImageMagick).
106     *
107     * @param blob the blob of a picture
108     * @return the {@link ImageInfo} of a blob
109     */
110    ImageInfo getImageInfo(Blob blob);
111
112    /**
113     * Returns the value a configuration which name is received as parameter.
114     *
115     * @param configurationName the name of the configuration
116     * @return the value of the configuration, which can be null in case no configuration with the specified name was
117     *         registered
118     */
119    String getConfigurationValue(String configurationName);
120
121    /**
122     * Returns the value a configuration which name is received as parameter. In case no configuration with the
123     * specified name was registered, the received <b>defaultValue</b> parameter will be returned.
124     *
125     * @param configurationName the name of the configuration
126     * @param defaultValue the value of the configuration
127     */
128    String getConfigurationValue(String configurationName, String defaultValue);
129
130    /**
131     * Sets the value of a configuration which could be used by the ImagingService.
132     *
133     * @param configurationName the name of the configuration
134     * @param configurationValue the value of the configuration
135     */
136    void setConfigurationValue(String configurationName, String configurationValue);
137
138    /**
139     * Computes a {@link PictureView} for the given {@code blob} and {@code pictureConversion}.
140     *
141     * @param convert true if the {@code blob} is converted to fit the {@code pictureConversion}, false if the
142     *            {@code blob} is put as it in the PictureView (without any conversion)
143     * @return the computed picture view
144     * @since 5.7
145     */
146    PictureView computeViewFor(Blob blob, PictureConversion pictureConversion, boolean convert) throws IOException;
147
148    /**
149     * Computes a {@link PictureView} for the given {@code blob} and {@code pictureConversion}.
150     *
151     * @param imageInfo the {@code ImageInfo} to use when computing the view
152     * @param convert true if the {@code blob} is converted to fit the {@code pictureConversion}, false if the
153     *            {@code blob} is put as it in the PictureView (without any conversion)
154     * @return the computed picture view
155     * @since 5.7
156     */
157    PictureView computeViewFor(Blob blob, PictureConversion pictureConversion, ImageInfo imageInfo, boolean convert)
158            throws IOException;
159
160    /**
161     * Computes a List of {@link PictureView}s for the given {@code blob} and {@code pictureConversions}.
162     *
163     * @param convert true if the {@code blob} is converted to fit each {@code PictureConversion}, false if the
164     *            {@code blob} is put as it in the PictureView (without any conversion)
165     * @return the computed picture views as a List of {@code PictureView}s
166     * @since 5.7
167     */
168    List<PictureView> computeViewsFor(Blob blob, List<PictureConversion> pictureConversions, boolean convert)
169            throws IOException;
170
171    /**
172     * Computes a List of {@link PictureView}s for the given {@code blob} and {@code pictureConversions}.
173     *
174     * @param imageInfo the {@code ImageInfo} to use when computing the view
175     * @param convert true if the {@code blob} is converted to fit each {@code PictureConversion}, false if the
176     *            {@code blob} is put as it in the PictureView (without any conversion)
177     * @return the computed picture views as a List of {@code PictureView}s
178     * @since 5.7
179     */
180    List<PictureView> computeViewsFor(Blob blob, List<PictureConversion> pictureConversions, ImageInfo imageInfo,
181            boolean convert) throws IOException;
182
183    /**
184     * Computes a List of all {@link PictureView}s for each {@link Blob} of {@code blobs}.
185     *
186     * @param convert true if the {@code blob} is converted to fit each {@code PictureConversion}, false if the
187     *            {@code blob} is put as it in the PictureView (without any conversion)
188     * @since 5.7
189     */
190    List<List<PictureView>> computeViewsFor(List<Blob> blobs, List<PictureConversion> pictureConversions,
191            boolean convert) throws IOException;
192
193    /**
194     * Computes a List of all {@link PictureView}s for each {@link Blob} of {@code blobs}.
195     *
196     * @param imageInfo the {@code ImageInfo} to use when computing the view
197     * @param convert true if the {@code blob} is converted to fit each {@code PictureConversion}, false if the
198     *            {@code blob} is put as it in the PictureView (without any conversion)
199     * @since 5.7
200     */
201    List<List<PictureView>> computeViewsFor(List<Blob> blobs, List<PictureConversion> pictureConversions,
202            ImageInfo imageInfo, boolean convert) throws IOException;
203
204    /**
205     * Compute all the registered {@link PictureConversion} For each picture template the
206     * {@link ImagingService#computeViewFor(Blob, PictureConversion, ImageInfo, boolean)} method is call
207     *
208     * @since 7.1
209     */
210    List<PictureView> computeViewsFor(DocumentModel doc, Blob blob, ImageInfo imageInfo, boolean convert) throws IOException;
211
212}