org.geolatte.mapserver.img.Imaging Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of geolatte-mapserver Show documentation
An embeddable map server supporting the WMS, WMTS and TMS protocols
The newest version!
/*
 * Copyright 2009-2010  Geovise BVBA, QMINO BVBA
 *
 * This file is part of GeoLatte Mapserver.
 *
 * GeoLatte Mapserver is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * GeoLatte Mapserver is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with GeoLatte Mapserver.  If not, see .
 */

package org.geolatte.mapserver.img;

import org.geolatte.geom.crs.CrsId;
import org.geolatte.mapserver.tms.MapUnitToPixelTransform;
import org.geolatte.mapserver.tms.TileImage;
import org.geolatte.mapserver.util.PixelRange;

import java.awt.*;
import java.awt.geom.AffineTransform;
import java.io.IOException;
import java.io.InputStream;
import java.util.Set;

/**
 * An API for the creation and manipulation of {@link TileImage}s.
 * 
 * 
Implementations are required to be thread-safe.
 * 
 *
 * @author Karel Maesen, Geovise BVBA
 */
public interface Imaging {

    /**
     * Scales a TileImage to the specified Dimensions
     *
     * @param image     the TileImage to scale
     * @param dimension the dimensions to which to scale
     * @return the scaled TileImage
     */
    public abstract TileImage scale(TileImage image, Dimension dimension);

    /**
     * Scales a TileImage with the specified scale-factors.
     *
     * @param image  the TileImage to scale
     * @param xScale the scale-factor along the X-axis
     * @param yScale the scale-factor along the Y-axis
     * @return the scaled TileImage
     */
    public abstract TileImage scale(TileImage image, float xScale, float yScale);

    /**
     * Reads a TileImage from an InputStream.
     *
     * @param inStream InputStream from which the TileImage is read
     * @param x        the minimum X-coordinate for the TileImage
     * @param y        the minimum Y-coordinate for the TileImage
     * @param forceArgb force the conversion of tile images to ARGB
     * @return the TileImage provided by the input stream
     * @throws IOException
     */
    public abstract TileImage read(InputStream inStream, int x, int y, boolean forceArgb) throws IOException;

    /**
     * Mosaics a set of TileImages.
     * 
     * 
The resulting TileImage has the specified PixelRange.
     * 
     *
     * @param images TileImages to mosaic.
     * @param bounds the PixelRange for the mosaic
     * @return the mosaic of the input TileImages
     */
    public abstract TileImage mosaic(Set images, PixelRange bounds);

    /**
     * Crops a TileImage to the specified PixelRange.
     *
     * @param image      the TileImge to crop
     * @param cropBounds the PixelRange to which to crop
     * @return the cropped TileImage
     */
    public abstract TileImage crop(TileImage image, PixelRange cropBounds);

    /**
     * Creates an empty image with the same characteristics as the specified
     * template TileImage.
     * 
     * 
If the template TileImage supports transparency, then the
     * created TileImage must be transparent. If not, then it
     * should be completely white.
     *
     * @param template  TileImage from which to copy the image characteristics.
     * @param dimension the dimensions of the empty TileImage
     * @return a fully transparent, or completely white TileImage
     */
    public abstract TileImage createEmptyImage(TileImage template, Dimension dimension);

    /**
     * Creates an empty image of the specified ImageFormat.
     * 

     * If the specified format supports transparency, then the
     * created TileImage must be transparent. If not, then it
     * should be completely white.
     *
     * @param dimension the dimensions of the empty TileImage
     * @param format    the ImageFormat to which the result can be written
     * @return a fully transparent, or completely white TileImage, depending
     *         on whether the format supports transparency or not
     */
    public abstract TileImage createEmptyImage(Dimension dimension, ImageFormat format);

    /**
     * Applies an AffineTransform to the specified TileImage.
     *
     * @param source the TileImage to be transformed
     * @param atf    the transform to be applied
     * @return the result of applying the transform to the
     *         source TileImage
     */
    public abstract TileImage affineTransform(TileImage source, AffineTransform atf);

    /**
     * Overlays to TileImages.
     *
     * @param source1 the first TileImage
     * @param source2 the TileImage which is to be overlayed on top of the first.
     * @return the overlay of the source TileImages and having the same PixelRange
     *         as the first source.
     */
    public TileImage overlay(TileImage source1, TileImage source2);


    /**
     * Approximates a reprojection of the source TileImage from source to target SRS
     * by warping (rubber-sheeting).
     *
     * @param source the source image
     * @param sourceSRS the source SRS
     * @param mupSrcTransform
     * @param targetSRS the target SRS
     * @param mupTargetTransform
     * @param tolerance the tolerance for the approximation
     * @return
     */
    public TileImage reprojectByWarping(TileImage source, MapUnitToPixelTransform mupSrcTransform, CrsId sourceSRS, CrsId targetSRS,  MapUnitToPixelTransform mupTargetTransform, double tolerance);
}