axis : doc

src/main/java/fr/ill/ics/n3d/model/Axis.java

@@ -19,11 +19,14 @@ import javafx.scene.transform.Transform;
 import javafx.scene.transform.Translate;
 
 /**
+ * Class representing the axis of a component. 
  * @author dages
- *
  */
 public class Axis {
 	
+	/**
+	 * Allowed axis types.
+	 */
 	public enum Type {
 		/** 1 translational DOF. */
 		TRANSLATION("Translation", Color.color(1, 1, 0)),
@@ -34,14 +37,27 @@ public class Axis {
 		/** 6 DOFs, ie the component is free. */
 		NONE("None", Color.color(1, 1, 1));
 		
+		/** String representation of the type. */
 		private String name;
+		
+		/** Color associated with the type. Used for visualizing axes. */
 		private Color color;
 		
+		/**
+		 * Constructor.
+		 * @param name String representation of the type
+		 * @param color Color associated with the type
+		 */
 		Type(String name, Color color) {
 			this.name = name;
 			this.color = color;
 		}
 		
+		/**
+		 * Conversion of a string to an axis type.
+		 * @param name String representation of the type
+		 * @return The type if the name is known, null otherwise
+		 */
 		public static Type fromString(String name) {
 			switch(name) {
 				case "Translation":
@@ -58,12 +74,20 @@ public class Axis {
 			}
 		}
 		
+		/**
+		 * Conversion of this type to a string.
+		 * @return String representation of the type
+		 */
 		@Override
 		public String toString() {
 			return this.name;
 		}
 	}
 	
+	/**
+	 * Methods used to compute an axis.
+	 * @author dages
+	 */
 	public enum Method {
 		/** Axis computed by this application. */
 		COMPUTED("Computed"),
@@ -72,12 +96,22 @@ public class Axis {
 		/** No info, computation needed. */
 		TO_COMPUTE("ToCompute");
 		
+		/** String representation of the method. */
 		private String name;
 		
+		/**
+		 * Constructor.
+		 * @param name String representation of the method
+		 */
 		Method(String name) {
 			this.name = name;
 		}
 
+		/**
+		 * Conversion of a string to an axis method.
+		 * @param name String representation of the method
+		 * @return The method if the name is known, null otherwise
+		 */
 		public static Method fromString(String name) {
 			switch(name) {
 				case "Computed":
@@ -91,18 +125,25 @@ public class Axis {
 			}
 		}
 
+		/**
+		 * Conversion of this method to a string.
+		 * @return String representation of the method
+		 */
 		@Override
 		public String toString() {
 			return this.name;
 		}
 	}
 	
+	/** Free axis, 6 DOFs. */
 	public static final Axis FREE_AXIS;
 	static {
 		FREE_AXIS = new Axis();
 		FREE_AXIS.setType(Type.NONE);
 		FREE_AXIS.setMethod(Method.COMPUTED);
 	}
+	
+	/** Fixed axis, 0 DOFs. */
 	public static final Axis FIXED_AXIS;
 	static {
 		FIXED_AXIS = new Axis();
@@ -110,23 +151,42 @@ public class Axis {
 		FIXED_AXIS.setMethod(Method.COMPUTED);
 	}
 	
+	/** Threshold, used for axes computations. */
 	private static final double EPSILON = 1e-1;
 	
+	/** Type of the axis. */
 	private Type type;
+	
+	/** Method used to get this axis. */
 	private Method method;
 	
+	/** Direction of the axis. This should be a unit vector. */
 	private Point3D direction;
+	
+	/** Position of the axis, in scene coordinate system. */
 	private Point3D position;
 	
+	/** Current value of the axis. */
 	private double value;
+	
+	/** Minimum value of the axis. */
 	private double minValue;
+	
+	/** Maximum value of the axis. */
 	private double maxValue;
+	
+	/** Median value of the axis. */
 	private double medianValue;
 	
 	/** Transform applied by the user when moving the component along its axis. */
 	private Affine movementTransform;
 	
+	/** Visual group of the axis. */
 	private Group visualGroup;
+	
+	/** Transform used convert scene coordinates into parent's coordinates. 
+	 * This parent is either the parent of the axis' component or the component itself if it is the root.
+	 */
 	private Transform sceneToParent;
 
 	/**
@@ -147,6 +207,10 @@ public class Axis {
 		this.sceneToParent = new Affine();
 	}
 	
+	/**
+	 * Copy constructor.
+	 * @param a Axis to copy
+	 */
 	public Axis(Axis a) {
 		this.type = a.type;
 		this.method = a.method;
@@ -162,90 +226,182 @@ public class Axis {
 		updateVisualGroup();
 	}
 	
+	/**
+	 * Gets the type of the axis
+	 * @return The type
+	 */
 	public Type getType() {
 		return this.type;
 	}
 
+	/**
+	 * Gets the method of the axis
+	 * @return The method
+	 */
 	public Method getMethod() {
 		return this.method;
 	}
 
+	/**
+	 * Gets the direction of the axis
+	 * @return The direction
+	 */
 	public Point3D getDirection() {
 		return this.direction;
 	}
 
+	/**
+	 * Gets the position of the axis
+	 * @return The position
+	 */
 	public Point3D getPosition() {
 		return this.position;
 	}
 
+	/**
+	 * Gets the value of the axis
+	 * @return The value
+	 */
 	public double getValue() {
 		return this.value;
 	}
 
+	/**
+	 * Gets the minimum value of the axis
+	 * @return The minimum value
+	 */
 	public double getMinValue() {
 		return minValue;
 	}
 
+	/**
+	 * Gets the maximum value of the axis
+	 * @return The maximum value
+	 */
 	public double getMaxValue() {
 		return maxValue;
 	}
 
+	/**
+	 * Gets the median value of the axis
+	 * @return The median value
+	 */
 	public double getMedianValue() {
 		return medianValue;
 	}
 
+	/**
+	 * Gets the movement transform of the axis
+	 * @return The movement transform
+	 */
 	public Affine getMovementTransform() {
 		return movementTransform;
 	}
 
+	/**
+	 * Gets the visual group of the axis
+	 * @return The visual group
+	 */
 	public Group getVisualGroup() {
 		return this.visualGroup;
 	}
 
+	/**
+	 * Gets the scene to parent transform of the axis
+	 * @return The scene to parent transform
+	 */
 	public Transform getSceneToParent() {
 		return sceneToParent;
 	}
 	
+	/**
+	 * Sets the type of the axis. 
+	 * @param type New type
+	 */
 	public void setType(Type type) {
 		this.type = type;
 		updateVisualGroup();
 	}
 	
+	/**
+	 * Sets the method of the axis
+	 * @param method New method
+	 */
 	public void setMethod(Method method) {
 		this.method = method;
 	}
 	
+	/**
+	 * Sets the direction of the axis. The new direction should be a unit vector. No verification is performed.
+	 * @param direction New direction. 
+	 */
 	public void setDirection(Point3D direction) {
 		this.direction = direction;
 		updateVisualGroup();
 	}
 	
+	/**
+	 * Sets the position of the axis.
+	 * @param position New position
+	 */
 	public void setPosition(Point3D position) {
 		this.position = position;
 		updateVisualGroup();
 	}
 	
+	/**
+	 * Sets the value of the axis, without moving it.
+	 * @see #move(double)
+	 * @param value New value
+	 */
 	public void setValue(double value) {
 		this.value = value;
 	}
 	
+	/**
+	 * Sets the minimum value of the axis.
+	 * @param minValue New minimum value
+	 */
 	public void setMinValue(double minValue) {
 		this.minValue = minValue;
 	}
 	
+	/**
+	 * Sets the maximum value of the axis.
+	 * @param maxValue New maximum value
+	 */
 	public void setMaxValue(double maxValue) {
 		this.maxValue = maxValue;
 	}
 	
+	/**
+	 * Sets the median value of the axis.
+	 * @param medianValue New median value
+	 */
 	public void setMedianValue(double medianValue) {
 		this.medianValue = medianValue;
 	}
 	
+	/**
+	 * Sets the scene to parent transform of the axis.
+	 * @param sceneToParent New transform
+	 */
 	public void setSceneToParent(Transform sceneToParent) {
 		this.sceneToParent = sceneToParent;
 		updateVisualGroup();
 	}
 	
+	/**
+	 * Updates the visual group of the axis. 
+	 * 
+	 * This method should be called when any of the following attributes of  the axis is changed :
+	 * <ul>
+	 * <li> direction </li>
+	 * <li> position </li>
+	 * <li> type </li>
+	 * <li> scene to parent transform </li>
+	 * </ul>
+	 */
 	private void updateVisualGroup() {
 		this.visualGroup.getChildren().clear();
 		this.visualGroup.getTransforms().clear();
@@ -281,6 +437,12 @@ public class Axis {
 		this.visualGroup.setDepthTest(DepthTest.DISABLE);
 	}
 
+	/**
+	 * Computes the axis described by a set of SolidWorks mates (constraints).
+	 * @param mates Set of mates 
+	 * @param config Configuration owning the mates
+	 * @return The computed axis
+	 */
 	public static Axis fromMates(HashSet<Mate> mates, ConfigParams config) {
 		Axis translation = new Axis();
 		translation.setType(Type.NONE);
@@ -309,6 +471,10 @@ public class Axis {
 		// return (translation.getType() == Type.TRANSLATION) ? translation : rotation; / priority to translation
 	}
 	
+	/**
+	 * Moves the axis according to a value. After this call, the value of the axis is incremented by the moving value.
+	 * @param value Moving value
+	 */
 	public void move(double value) {
 		if (Math.abs(value) < EPSILON) {
 			return;
@@ -343,6 +509,12 @@ public class Axis {
 		}
 	}
 	
+	/**
+	 * Moves the axis. This is a convenience method to handle mouse entries.
+	 * @param delta Mouse movement's delta
+	 * @param screenAxisDir Axis direction in screen coordinates
+	 * @param multiplier Multiplier of the movement amplitude
+	 */
 	void move(Point2D delta, Point2D screenAxisDir, double multiplier) {
 		double coef = 0;
 		switch (this.type) {
@@ -367,12 +539,20 @@ public class Axis {
 		this.move(multiplier * coef);
 	}
 	
+	/**
+	 * Resets the movement.
+	 */
 	public void resetMovement() {
 		this.value = 0;
 		this.movementTransform.setToIdentity();
 		this.move(this.medianValue);
 	}
 	
+	/**
+	 * Clones this axis.
+	 * @return A copy of this axis
+	 */
+	@Override
 	public Axis clone() {
 		return new Axis(this);
 	}