bundles/examples/org.eclipse.apogy.examples.lidar/model/apogy_examples_lidar.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="ApogyExamplesLidar",
		  childCreationExtenders="true",
		  extensibleProviderFactory="true",
		  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="ApogyExamplesLidar",
		  suppressGenModelAnnotations="false",
		  dynamicTemplates="true", 
		  templateDirectory="platform:/plugin/org.eclipse.apogy.common.emf.codegen/templates")
@GenModel(modelDirectory="/org.eclipse.apogy.examples.lidar/src-gen")
@GenModel(editDirectory="/org.eclipse.apogy.examples.lidar.edit/src-gen")

package org.eclipse.apogy.examples.lidar

import org.eclipse.apogy.addons.sensors.fov.RectangularFrustrumFieldOfView
import org.eclipse.apogy.common.geometry.data3d.CartesianCoordinatesSet
import org.eclipse.apogy.common.Apogy


/*
 * Apogy Example Lidar Facade.
 */
@Apogy(isSingleton="true", hasCustomClass="true")
class ApogyExampleLidar{
	/**
	 * Returns a new Lidar object, which has the same type as
	 * the given Lidar unit.
	 * 
	 * @param lidar The Lidar unit with a particular implementation. 
	 * @return The new Lidar instance, which has the same type as the other one
	 */	
	op Lidar makeLidarSameType(Lidar lidar)
}
	
/** 
 * This is an abstraction of the Lidar unit, a 3D laser-based range
 * finder which is capable of scanning the environment and returning
 * a point cloud encompassing the resulting information.  It has a
 * field of view, which determines the subsection of the environment
 * that the unit can scan.  It also can keep track of whether or not
 * the unit was initialized.
 */
@Apogy(hasCustomClass="true")
abstract class Lidar
{
	/**
	 * This is the Lidar's field of view, which corresponds to a rectangular
	 * frustrum with defined limits.
	 */
	@GenModel(children="true",
			  notify="true",
			  property="Readonly",
			  propertyCategory="Field Of View")
	contains RectangularFrustrumFieldOfView[1] fov

	/**
	 * This is whether or not the Lidar unit has been been successfully
	 * initialized; initially false.
	 * @see #init()
	 */
	@GenModel(children="false",
			  notify="true",
			  property="Readonly",
			  propertyCategory="Status")
	boolean initialized = "false"

	/**
	 * This operation is used to perform the steps necessary to initialize
	 * the Lidar unit.
	 * @return Whether or not the Lidar's initialization was successfully completed
	 */
	op boolean init()
	 
	/**
	 * This operation is used to acquire a depth scan of the field of view, with the given
	 * horizontal and vertical resolution.
	 * <p>
	 * Note: This method operates synchronously and will block until the entire scan has been
	 *       completed.  
	 * @param horizontalResolution The horizontal angular resolution of the scan (in radians.)
	 * @param verticalResolution The vertical angular resolution of the scan (in radians.)
	 * @return The resulting scan with the given horizontal and vertical angular resolution.
	 * @see #acquireScanNonBlocking(double, double)
	 */
	op CartesianCoordinatesSet acquireScan(@Apogy(units="rad") double horizontalResolution,
										   @Apogy(units="rad") double verticalResolution)
	
	/** 
	 * This operation is used to acquire a depth scan of the field of view, with the given
	 * horizontal and vertical resolution.
	 * <p>
	 * Note: This method operates asynchronously and as such, will return immediately, even
	 *       if the scan is not yet completed.
	 * @param horizontalResolution The horizontal angular resolution of the scan (in radians.)
	 * @param verticalResolution The vertical angular resolution of the scan (in radians.)
	 * @return The resulting scan with the given horizontal and vertical angular resolution.
	 * @see #acquireScan(double, double)
	 */
	op CartesianCoordinatesSet acquireScanNonBlocking(@Apogy(units="rad") double horizontalResolution,
													  @Apogy(units="rad") double verticalResolution)
}

/** 
 * This is a specific implementation of the Lidar unit, in which
 * all operations are stubs and hence, non-functional; the
 * operations should simply log a message, indicating that they
 * were performed.
 */
@Apogy(hasCustomClass="true", hasCustomItemProvider="true")
class LidarStub extends Lidar
{
	/**
	 * For specific implementation details,
	 * see {@link org.eclipse.apogy.examples.lidar.impl.LidarStubImpl}
	 */
}

/**
 * This is a simulated implementation of the Lidar unit, where all
 * operations are executed upon a simulated (i.e. virtual) Lidar.
 * The current version returns a point cloud of randomly generated points.
 */
@Apogy(hasCustomClass="true", hasCustomItemProvider="true")
class LidarSimulated extends Lidar
{
	/**
	 * For specific implementation details,
	 * see {@link org.eclipse.apogy.examples.lidar.impl.LidarSimulatedImpl}
	 */
}