bundles/common/org.eclipse.apogy.common.images/model/apogy_common_images.xcore

// *****************************************************************************
// Copyright (c) 2018 Agence spatiale canadienne / Canadian Space Agency 
// All rights reserved. This program and the accompanying materials
// are made available under the terms of the Eclipse Public License v1.0
// which accompanies this distribution, and is available at
// http://www.eclipse.org/legal/epl-v10.html
// 
// Contributors:
//     Pierre Allard - initial API and implementation
//     Regent L'Archeveque
//        
// SPDX-License-Identifier: EPL-1.0
// *****************************************************************************

@GenModel(prefix="ApogyCommonImages",
	      childCreationExtenders="true",
	      extensibleProviderFactory="true",
	      multipleEditorPages="false",
copyrightText="*******************************************************************************
Copyright (c) 2018 Agence spatiale canadienne / Canadian Space Agency 
All rights reserved. This program and the accompanying materials
are made available under the terms of the Eclipse Public License v1.0
which accompanies this distribution, and is available at
http://www.eclipse.org/legal/epl-v10.html

Contributors:
     Pierre Allard - initial API and implementation
     Regent L'Archeveque
        
SPDX-License-Identifier: EPL-1.0    
*******************************************************************************",
	      modelName="ApogyCommonImages",
	      suppressGenModelAnnotations="false")
@GenModel(dynamicTemplates="true", templateDirectory="platform:/plugin/org.eclipse.apogy.common.emf.codegen/templates")	      
@GenModel(modelDirectory="/org.eclipse.apogy.common.images/src-gen")
@GenModel(editDirectory="/org.eclipse.apogy.common.images.edit/src-gen")
		  
package org.eclipse.apogy.common.images

// Types

import org.eclipse.apogy.common.Apogy

type List<T> wraps java.util.List
type ImageData wraps org.eclipse.swt.graphics.ImageData
type BufferedImage wraps java.awt.image.BufferedImage
type Exception wraps Exception
type Color wraps java.awt.Color
type Font wraps java.awt.Font

/**
 * An image album.
 */
class ImagesAlbum
{
	/**
	 * Name of the Album.
	 */
	String name
	
	/**
	 * List of images composing the Album.
	 */
	contains AbstractEImage[] images
}

/**
 * Base class representing an image.
 */
interface AbstractEImage
{
	/**
	 * Width of the image.
	 */
	@Apogy(units="pixel")
	int width = "-1"

	/**
	 * Height of the image.
	 */
	@Apogy(units="pixel")
	int height = "-1"

	/**
	 * Return the image as a BufferedImage.
	 */
	op BufferedImage asBufferedImage()
}

/**
 * A concrete implementation of AbstractEImage that stores the image content as a BufferedImage.
 */
@Apogy(hasCustomClass="true")
class EImage extends AbstractEImage
{
	/**
	 * The image content.
	 */
	BufferedImage imageContent
}

/**
 * A concrete implementation of AbstractEImage that refers to a file storing the image content.
 */
@Apogy(hasCustomClass="true")
class URLEImage extends AbstractEImage
{
	/**
	 * URL to the resource containing the Image.
	 */
	String url
}

/**
 * Image Utilities functions.
 */
@Apogy(isSingleton="true", hasCustomClass="true")
class EImagesUtilities
{
	/**
	 * Create a copy of an AbstractEImage.
	 * @param originalImage The original AbstractEImage.
	 * @return The copy.
	 */
	op AbstractEImage copy(AbstractEImage originalImage)

	/**
	 * Create a grey scaled copy of an AbstractEImage.
	 * @param originalImage The original AbstractEImage.
	 * @return The grey scale copy.
	 */
	op AbstractEImage convertToGrayScale(AbstractEImage originalImage)

	/**
	 * Creates a resized copy of an AbstractEImage.
	 * @param originalImage The original AbstractEImage.
	 * @param scaleFactor The scaling factor. Must be greater than zero.
	 * @return The resized copy.
	 */
	op AbstractEImage resize(AbstractEImage originalImage , double scaleFactor)

	/**
	 * Creates a resized copy of an AbstractEImag with one scale factor per image dimensions.
	 * @param originalImage The original AbstractEImage.
	 * @param widthScaleFactor The scaling factor to be applied along the width of the image. Must be greater than zero.
	 * @param heightScaleFactor The scaling factor to be applied along the height of the image. Must be greater than zero.
	 * @return The resized copy.
	 */
	op AbstractEImage resize(AbstractEImage originalImage , double widthScaleFactor , double heightScaleFactor)

	/**
	 * Creates a resized copy of an AbstractEImag to specified width and height.
	 * @param originalImage The original AbstractEImage.
	 * @param newWidth The target width of the copied. Must be greater than zero.
	 * @param newHeight The target height of the copied image. Must be greater than zero.
	 * @return The resized copy.
	 */
	op AbstractEImage resize(AbstractEImage originalImage , @Apogy(units="pixel") int newWidth , @Apogy(units="pixel")  int newHeight)

	/**
	 * Creates a transparent image of specified dimensions.
	 * @param width Width of the image.
	 * @param height Height of the image.
	 * @return The transparent image.
	 */
	op AbstractEImage createTransparentImage(int width , int height)

	/**
	 * Saves a given image to file in JPEG format.
	 * @param destinationFilePath Absolute path of the file where to save the image, should not include the file extension.
	 * @param image The AbstractEImage to save.
	 * @throws An exception if the save fails.
	 */
	op void saveImageAsJPEG(String destinationFilePath , AbstractEImage image) throws Exception

	/**
	 * Saves a given image to file in PNG format.
	 * @param destinationFilePath Absolute path of the file where to save the image, should not include the file extension.
	 * @param image The AbstractEImage to save.
	 * @throws An exception if the save fails.
	 */
	op void saveImageAsPNG(String destinationFilePath , AbstractEImage image) throws Exception

	/**
	 * Return an image that is the result of overlaying an image on top of an original image.
	 * @param originalImage The original image.
	 * @param overlayImage The overlaid image (i.e. the put on top of the original image).
	 * @param allowOverlayResize Whether or not to allow the overlay image to be resized to match the size of the original image (
	 * The overlay image aspect ratio may be changed).  
	 * @return The resulting image.
	 */
	op AbstractEImage applyOverlay(AbstractEImage originalImage , AbstractEImage overlayImage , boolean allowOverlayResize)

	/**
	 * Returns an image that is a copy of the original flipped about the horizontal axis.
	 * @param originalImage The original image.
	 * @return The flipped image.
	 */
	op AbstractEImage flipHorizontal(AbstractEImage originalImage)

	/**
	 * Returns an image that is a copy of the original flipped about the vertical axis.
	 * @param originalImage The original image.
	 * @return The flipped image.
	 */
	op AbstractEImage flipVertical(AbstractEImage originalImage)

	/**
	 * Returns an image that is a copy of the original rotated about its upper left corner by a specified angle.
	 * @param originalImage The original image.
	 * @param angle The rotation angle in radians.
	 * @param enableImageResize Whether or not to allow the rotated image to be resized to contain all the rotated pixels.
	 * @return The rotated image.
	 */
	op AbstractEImage rotate(AbstractEImage originalImage , @Apogy(units="rad") double angle , boolean enableImageResize)

	/**
	 * Returns an image that is a copy of the original translated by a number of pixel in the vertical and horizontal directions.
	 * @param originalImage The original image.
	 * @param widthTranslation The translation along the width of the image, in pixels.
	 * @param heightTranslation The translation along the height of the image, in pixels.
	 * @return The translated image. This image is made large enough to contain the original image + the translations.
	 */
	op AbstractEImage translate(AbstractEImage originalImage , @Apogy(units="pixel") int widthTranslation , @Apogy(units="pixel") int heightTranslation)

	/**
	 * Return the image size that would envelop all images in a list,
	 * @param images The list of images.
	 * @return The image size.
	 */
	op ImageSize getAllEncompassingImageSize(List < ? extends AbstractEImage > images)

	/**
	 * Create an image that is the result of stacking a list of images on top of each other.
	 * @param images The list of images.
	 * @param allowImageResize Whether or not to allow images being resized to match the previous one size.
	 * @param alignment Alignment to be used when stacking images.
	 * @return The resulting image. 
	 */
	op AbstractEImage superPoseImages(List < ? extends AbstractEImage > images , boolean allowImageResize , ImageAlignment alignment)

	/**
	 * Create an image that is the result of stacking two images on top of each other.
	 * @param imageA The first image. 
	 * @param imageB The second image. Will be stacked on top of the first one.
	 * @param allowImageResize Whether or not to allow imageB being resized to match imageA size.
	 * @param alignment Alignment to be used when stacking imageB onto imageA.
	 * @return The resulting image. 
	 */
	op AbstractEImage superPoseImages(AbstractEImage imageA , AbstractEImage imageB , boolean allowImageResize , ImageAlignment alignment)

	/**
	 * Creates an image that is a copy of the original with a border drawn on the inside of its perimeter (i.e. the image size is not changed).
	 * @param originalImage The original image.
	 * @param borderWidth The width of the border, in pixel.
	 * @param red The red component of the border color, between 0 and 255.
	 * @param green The green component of the border color, between 0 and 255.
	 * @param blue The blue component of the border color, between 0 and 255.
	 * @return The resulting image. 
	 */
	op AbstractEImage addBorder(AbstractEImage originalImage , @Apogy(units="pixel") int borderWidth , int red , int green , int blue)

	/**
	 * Gets a sub image from a specified image. Note that the widthOffset and heightOffset are relative to the upper left corner of the image.
	 * @param originalImage The original image.
	 * @param widthOffset The sub-image offset along the width of the original, in pixels.
	 * @param heightOffset The sub-image offset along the height of the original, in pixels.
	 * @param subImageWidth The width of the sub-image, in pixels.
	 * @param subImageHeight The height of the sub-image, in pixels.
	 * @return The sub image.
	 * @throws An exception if the offsets of the sub-image does not fall inside the original.
 	 */
	op AbstractEImage getSubImage(AbstractEImage originalImage , @Apogy(units="pixel") int widthOffset , @Apogy(units="pixel") int heightOffset , 
								  @Apogy(units="pixel") int subImageWidth , @Apogy(units="pixel")int subImageHeight) throws Exception

	/**
	 * Converts an ImageData to a BufferedImage.
	 * @param imageData The ImageData to convert.
	 * @return The BufferedImage.
	 */
	op BufferedImage convertToBufferedImage(ImageData imageData)

	/**
	 * Converts an BufferedImage to an ImageData.
	 * @param bufferedImage The BufferedImage to convert.
	 * @return The ImageData.
	 */
	op ImageData convertToImageData(BufferedImage bufferedImage)

	/**
	 * Creates an image of uniform color of specified dimensions.
	 * @param width Width of the image, in pixels.
	 * @param height Height of the image, in pixels.
	 * @param red The red component of the image color, between 0 and 255.
	 * @param green The green component of the image color, between 0 and 255.
	 * @param blue The blue component of the image color, between 0 and 255.
	 * @param alpha The alpha component of the image color, between 0 (transparent) and 255 (opaque).
	 */
	op AbstractEImage createUniformColorImage(@Apogy(units="pixel") int width , @Apogy(units="pixel") int height , int red , int green , int blue , int alpha)

	/**
	 * Creates an image which is a copy of the original where the alpha component of the color of each pixel is set to a specified value.
	 * @param originalImage The original image.
	 * @param alpha The alpha component, from 0.0 (transparent) to 1.0 (opaque).
	 * @return The resulting image.
	 */
	op AbstractEImage applyAlpha(AbstractEImage originalImage , float alpha)

	/**
	 * Create an image which is a copy of the original on which an edge filter has been applied.
	 * @param originalImage The original image.
	 * @return The filtered image.
	 */
	op AbstractEImage applyEdgeFilter(AbstractEImage originalImage)

	/**
	 * Create an image which is a copy of the original on which an contrast and brightness filter has been applied.
	 * @param originalImage The original image.
	 * @param contrast The contrast gain.
	 * @param brightness The brightness gain.
	 * @return The filtered image.
	 */
	op AbstractEImage applyContrastAndBrightnessFilter(AbstractEImage originalImage , double contrast , double brightness)

	/**
	 * Create an image which is a copy of the original on which an exposure filter has been applied.
	 * @param originalImage The original image.
	 * @param exposure The exposure gain.	
	 * @return The filtered image.
	 */
	op AbstractEImage applyExposureFilter(AbstractEImage originalImage , double exposure)

	/**
	 * Create an image which is a copy of the original on which an color inverting filter has been applied.
	 * @param originalImage The original image.
	 * @return The filtered image.
	 */
	op AbstractEImage applyInvertFilter(AbstractEImage originalImage)

	/**
	 * Create an image which is a copy of the original on which an rescaling of intensity filter has been applied.
	 * @param originalImage The original image.
	 * @param scale The scaling gain.
	 * @return The filtered image.
	 */
	op AbstractEImage applyRescaleFilter(AbstractEImage originalImage , double scale)

	/**
	 * Create an image which is a copy of the original on which an gain of intensity filter has been applied.
	 * @param originalImage The original image.
	 * @param gain The intensity gain.
	 * @param bias Bias of the intensity.
	 * @return The filtered image.
	 */
	op AbstractEImage applyGainFilter(AbstractEImage originalImage , double gain , double bias)

	/**
	 * Creates an image of uniform color onto which text is rendered.
	 * @param text The text to render.
	 * @param font The font to use.
	 * @param textColor The color of the text.
	 * @param backgroundColor The color of the image background.
	 * @param borderWidth The width left empty (background color) around the text, in pixel.
	 * @return The resulting image.
	 */
	op AbstractEImage createTextImage(String text , Font font , Color textColor , Color backgroundColor , @Apogy(units="pixel") int borderWidth)
}


/**
 * A class representing an image size.
 */
class ImageSize
{
	/**
	 * Width of the image.
	 */
	@Apogy(units="pixel")
	int width = "-1"
	
	/**
	 * Height of the image.
	 */	
	@Apogy(units="pixel")
	int height = "-1"
}

/**
 * An interface for a provider of AbstractEImage.
 */
interface AbstractEImageProvider
{
	/**
	 * Returns an AbstractEImage.
	 * @return The AbstractEImage.
	 */
	op AbstractEImage getAbstractEImage()
}

/**
 * Defines image alignment.
 */
enum ImageAlignment
{
	CENTER = 1
	LOWER_LEFT_CORNER = 2
	UPPER_LEFT_CORNER = 3
	LOWER_RIGHT_CORNER = 4
	UPPER_RIGHT_CORNER = 5
}