bundles/addons/org.eclipse.apogy.addons.sensors.fov/model/apogy_addons_sensors_fov.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="ApogyAddonsSensorsFOV",
	      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="ApogyAddonsSensorsFOV",
	      suppressGenModelAnnotations="false",
		  dynamicTemplates="true", 
		  templateDirectory="platform:/plugin/org.eclipse.apogy.common.emf.codegen/templates")
@GenModel(modelDirectory="/org.eclipse.apogy.addons.sensors.fov/src-gen")
@GenModel(editDirectory="/org.eclipse.apogy.addons.sensors.fov.edit/src-gen")

package org.eclipse.apogy.addons.sensors.fov

import org.eclipse.apogy.common.math.Matrix4x4
import org.eclipse.apogy.common.math.Tuple3d

import org.eclipse.apogy.common.topology.Node
import org.eclipse.apogy.common.geometry.data3d.CartesianPolygon
import org.eclipse.apogy.common.geometry.data3d.CartesianPositionCoordinates
import org.eclipse.apogy.common.geometry.data.PolygonSamplingShape
import org.eclipse.apogy.common.geometry.data.CoordinatesSamplingShape
import org.eclipse.apogy.common.Apogy

/**
 * Base class for Field Of View
 */
abstract class FieldOfView extends Node
{	
	/**
	 * Whether or not the selected point visible from the FieldOfView (i.e. the selected point is not necessary inside the 
	 * the volume of the FieldOfView, but its angular coordinates are.)
	 * @param point The point, expressed in the FieldOfView reference frame.
	 * @return True is the point is visible, false otherwise.
	 */
	op boolean isPointVisible(Tuple3d point)
	
	/**
	 * Whether or not the selected point in inside the volume (or area) of the FieldOfView.
	 * @param point The point, expressed in the FieldOfView reference frame.
	 * @return True is the point is inside the FieldOfView volume, false otherwise.
	 */
	op boolean isPointInside(Tuple3d point)
}

/**
 * Defines an distance range by specifying a minimum and maximum distance.
 */
@Apogy(hasCustomClass="true", hasCustomItemProvider="true")
class DistanceRange
{
	/**
	 * The minimum range of the distance range.
	 */
	@Apogy(units="m")
	double minimumDistance = "0.0"
	
	/**
	 * The maximum range of the distance range.
	 */
	@Apogy(units="m")
	double maximumDistance = "1.0"
	
	/**
	 * The distance between the minium and maximum range.
	 */
	@Apogy(units="m")
	readonly transient volatile derived double distance
	
	/**
	 * Returns whether or not the specified distance falls within the range.
	 * @param distance The distance.
	 * @return True if the distance falls within the range (inclusive), false otherwise.
	 */
	op boolean isWithinRange(@Apogy(units="m") double distance)
}

/**
 * Defines an angular span by specifying a maximum and a minimum angle (in radians).
 */
@Apogy(hasCustomClass="true", hasCustomItemProvider="true")
class AngularSpan
{
	/**
	 * The minimum angle defining the angular range.
	 */
	@Apogy(units="rad")
	double minimumAngle = "0.0"
 	
 	/**
	 * The maximum angle defining the angular range.
	 */
	@Apogy(units="rad")
	double maximumAngle = "0.0"
 	
	/**
	 * The total angular span, in radians.
	 */
	@Apogy(units="rad")
	readonly transient volatile derived double spanningAngle
 	
	/**
	 * The center of the angular span, in radians.
	 */
	@Apogy(units="rad")
	readonly transient volatile derived double centerAngle
 	
	/**
	 * Returns whether or not the specified angle falls within the angular range (inclusive).
	 * @param angle The angle.
	 * @return True if the angle falls within the range (inclusive), false otherwise.
	 */
	op boolean isWithinRange(@Apogy(units="rad") double angle)
}
 
/**
 * A field of view that has a frustum shape. This frustum has a
 * rectangular base and is right (its axis is perpendicular to both bases).
 * @see http://en.wikipedia.org/wiki/Frustrum.
 */
@Apogy(hasCustomClass="true", hasCustomItemProvider="true")
class RectangularFrustrumFieldOfView extends FieldOfView
{
	/**
	 * The Distance Range of the frustum.
	 */
	contains DistanceRange range
 	
	/*
	 * Total horizontal field of view, in radians.
	 */
	@Apogy(units="rad")
	double horizontalFieldOfViewAngle
 	
	/*
	 * Total vertical field of view, in radians.
	 */
	@Apogy(units="rad")
	double verticalFieldOfViewAngle
 	
	/*
	 * The volume of the contained within the field of view.
	 */
	@Apogy(units="m^3")
	readonly volatile transient derived double volume		
}
 
 /**
  * A conical field of view defined by its apex angle.
  */
@Apogy(hasCustomClass="true", hasCustomItemProvider="true")
class ConicalFieldOfView extends FieldOfView
{
	/**
	 * The Distance Range of the cone.
	 */
	contains DistanceRange range
	
	/*
	 * The apex angle, in radians, of the conical field of view.
	 */
	@Apogy(units="rad")
	double fieldOfViewAngle
	
	/*
	 * The volume of the contained within the field of view.
	 */
	@Apogy(units="m^3")
	readonly volatile transient derived double volume
}

/**
 * A field of view shaped like a circular sector.
 * @see http://en.wikipedia.org/wiki/Circular_sector.
 */
@Apogy(hasCustomClass="true", hasCustomItemProvider="true")
class CircularSectorFieldOfView extends FieldOfView
{
	/**
	 * The Distance Range of the circular sector.
	 */
	contains DistanceRange range
	
	/**
	 * The angular span of the circular sector.
	 */
	contains AngularSpan [1] angularSpan
	
	/**
	 * The area of the circular sector.
	 */
	readonly volatile transient derived double area
}

/**
 * A sampling shape shaped as a Rectangular Frustrum Field Of View.
 */
@Apogy(hasCustomClass="true")
class RectangularFrustrumFieldOfViewSamplingShape<PolygonType extends CartesianPolygon> extends CoordinatesSamplingShape<CartesianPositionCoordinates>,
																								PolygonSamplingShape<CartesianPositionCoordinates, PolygonType>
{
	/**
	 * The transform of the sampling shape relative to the points to sanple.
	 */
	refers Matrix4x4 transform
	
	/**
	 * The RectangularFrustrumFieldOfView defining the sampling shape.
	 */
	refers RectangularFrustrumFieldOfView rectangularFrustrumFieldOfView
}

/**
 * Field Of View Facade.
 */
@Apogy(isSingleton="true", hasCustomClass="true")
class ApogyAddonsSensorsFOVFacade
{
	/**
	 * Creates a DistanceRange from minimum and maximum distances.
	 * @param minimumDistance The minimum distance, in meters.
	 * @param maximumDistance The maximum distance, in meters.
	 * @return The DistanceRange.
	 */
	op DistanceRange createDistanceRange(@Apogy(units="m") double minimumDistance, 
										 @Apogy(units="m") double maximumDistance)
	
	/**
	 * Creates a copy of a DistanceRange from a DistanceRange.
	 * @param distanceRange The original DistanceRange.
	 * @return The DistanceRange.
	 */
	op DistanceRange createDistanceRange(DistanceRange distanceRange)
	
	/**
	 * Creates an AngularSpan from a minimum and a maximum angle.
	 * @param minimumAngle The minimum angle, in radians.
	 * @param maximumAngle The maximum angle, in radians.
	 * @return The AngularSpan.
	 */
	op AngularSpan createAngularSpan(@Apogy(units="rad") double minimumAngle, 
									 @Apogy(units="rad") double maximumAngle)
	
	/**
	 * Creates a copy of a AngularSpan from a AngularSpan.
	 * @param angularSpan The original AngularSpan.
	 * @return The AngularSpan.
	 */
	op AngularSpan createAngularSpan(AngularSpan angularSpan)
	
	/**
	 * Creates a RectangularFrustrumFieldOfView from a minimum and maximum distancesm horizontal and vertical field of view angles.
	 * @param minimumDistance The minimum distance, in meters.
	 * @param maximumDistance The maximum distance, in meters.
	 * @param horizontalFieldOfViewAngle The horizontal field of view angle, in radians.
	 * @param verticalFieldOfViewAngle The vertical field of view angle, in radians.
	 * @return The RectangularFrustrumFieldOfView.
	 */
	op RectangularFrustrumFieldOfView createRectangularFrustrumFieldOfView(@Apogy(units="m") double minimumDistance, 
																		   @Apogy(units="m") double maximumDistance, 
																		   @Apogy(units="rad") double horizontalFieldOfViewAngle, 
																		   @Apogy(units="rad") double verticalFieldOfViewAngle)
	
	/**
	 * Creates a copy of a RectangularFrustrumFieldOfView from a RectangularFrustrumFieldOfView.
	 * @param rectangularFrustrumFieldOfView The original RectangularFrustrumFieldOfView.
	 * @return The RectangularFrustrumFieldOfView.
	 */
	op RectangularFrustrumFieldOfView createRectangularFrustrumFieldOfView(RectangularFrustrumFieldOfView rectangularFrustrumFieldOfView)
	
	/**
	 * Creates a ConicalFieldOfView from minimum and maximum distances and an field of view angle.
	 * @param minimumDistance The minimum distance, in meters.
	 * @param maximumDistance The maximum distance, in meters.
	 * @param fieldOfViewAngle The field of view angle, in radians.
	 * @return The ConicalFieldOfView.
	 */
	op ConicalFieldOfView createConicalFieldOfView(@Apogy(units="m") double minimumDistance, 
												   @Apogy(units="m") double maximumDistance, 
												   @Apogy(units="rad") double fieldOfViewAngle)
	
	/**
	 * Creates a copy of a ConicalFieldOfView from a ConicalFieldOfView.
	 * @param conicalFieldOfView The original ConicalFieldOfView.
	 * @return The ConicalFieldOfView.
	 */
	op ConicalFieldOfView createConicalFieldOfView(ConicalFieldOfView conicalFieldOfView)
	
	/**
	 * Creates a CircularSectorFieldOfView from minimum and maximum angles and distances.
	 * @param minimumAngle The minimum angle, in radians.
	 * @param maximumAngle The maximum angle, in radians.	 
	 * @param minimumDistance The minimum distance, in meters.
	 * @param maximumDistance The maximum distance, in meters.	 
	 * @return The CircularSectorFieldOfView.
	 */
	op CircularSectorFieldOfView createCircularSectorFieldOfView(@Apogy(units="m") double minimumAngle, 
																 @Apogy(units="rad") double maximumAngle, 
																 @Apogy(units="m") double minimumDistance, 
																 @Apogy(units="m") double maximumDistance)
	
	/**
	 * Creates a copy of a CircularSectorFieldOfView from a CircularSectorFieldOfView.
	 * @param circularSectorFieldOfView The original CircularSectorFieldOfView.
	 * @return The CircularSectorFieldOfView.
	 */
	op CircularSectorFieldOfView createCircularSectorFieldOfView(CircularSectorFieldOfView circularSectorFieldOfView)
}