GeomConverter/src/org/lcsim/geometry
diff -u -r1.19 -r1.20
--- IDDecoder.java 3 Feb 2010 01:43:42 -0000 1.19
+++ IDDecoder.java 5 Feb 2010 20:27:12 -0000 1.20
@@ -7,20 +7,24 @@
/**
*
- * Compact detector description interface for identifier handling.
+ * The compact detector description's interface for identifier decoding.
*
- * @author Tony Johnson
- * @author Jeremy McCormick
+ * @author tonyj
+ * @author jeremym
*/
+// List of TODOs
+// -------------
// TODO: The getX/Y/Z methods should be removed. Instead use getPosition()[i] or getPositionVec.x/y/z().
// TODO: The findCellContainingXYZ methods probably don't belong here. In general, hard to implement and not always implemented by subclasses.
-// TODO: The field-related methods should be on IDDescriptor. No need to push these methods up to here and clutters the interface.
-// TODO: The class hierarchy of implementations is overly complicated. (CalorimeterIDDecoder, geometry.util, segmentation, etc.)
-// TODO: Needs a method to get the current id.
+// This functionality should reside in a geometer class.
+// TODO: Do NOT need three similar versions of findCellContainingXYZ() in the interface, because it is confusing. One should be good enough.
+// TODO: The methods related to getting ID meta information should be left in IDDescriptor. No need to push these methods up to here and clutter the interface.
+// TODO: The class hierarchy of sub-classes far too complicated. (CalorimeterIDDecoder, geometry.util, segmentation, BaseIDDecoder, etc.)
// TODO: Methods like getSystemID() should use getValue("system") instead. Same for getLayer().
// TODO: The methods getPhi() and getTheta() can be easily computed from position or retrieved from position vector.
-// TODO: Need to find and refactor all code in lcsim and lcsim-contrib that uses methods to be deprecated or removed.
// TODO: The method getSubdetector() needs to be revisted. This should instead be retrieved from the hit's metadata.
+// TODO: In general, the fact that the decoder holds "state" of a current ID is not good and could potentially lead to some odd behaviors. A better
+// method signature would be getFieldValue("field", int id). Then there is no implied state in the decoder or interface.
public interface IDDecoder
{
/**
@@ -33,17 +37,54 @@
*/
public void setID(long id);
+ /**
+ * Get the value of the given field.
+ * @param field The name of the field.
+ * @return The integer value of the field.
+ */
public int getValue(String field);
+
+ /**
+ * Get the value of a field by index.
+ * @param index The index into the id.
+ * @return The integer value of the field.
+ */
public int getValue(int index);
+ /**
+ * Get the number of fields in this id description.
+ * @return The number of fields.
+ */
public int getFieldCount();
+
+ /**
+ * Get field name by index.
+ * @param index The index of the field.
+ * @return The field name.
+ */
public String getFieldName(int index);
+
+ /**
+ * Get field index by name.
+ * @param name The name of the field.
+ * @return The index of the field.
+ */
public int getFieldIndex(String name);
+
+ /**
+ * Set the ID description of this decoder.
+ * @param id The ID description.
+ */
public void setIDDescription(IDDescriptor id);
+
+ /**
+ * Get the ID description of this decoder.
+ * @return The ID description.
+ */
public IDDescriptor getIDDescription();
/**
- * Get the layer number.
+ * Get the layer number for the current id.
* @return layer number
*/
public int getLayer();
@@ -86,13 +127,27 @@
public double getPhi();
/**
- * @return theta angle
+ * The decoded theta angle of this id.
+ * @return The theta angle.
*/
public double getTheta();
+ /**
+ * Locate a cell from a global position.
+ * @param pos The position.
+ * @return The cell id.
+ */
public long findCellContainingXYZ(Hep3Vector pos);
+
+ /**
+ * Locate a cell from a global position.
+ * @param pos The position.
+ * @return The cell id.
+ */
public long findCellContainingXYZ(double[] pos);
- public long findCellContainingXYZ(double x, double y, double z);
+
+ // Removed. --JM
+ //public long findCellContainingXYZ(double x, double y, double z);
/**
* Get the flag that indicates barrel or endcap, i.e. the "barrel" field.
@@ -114,7 +169,24 @@
*/
public Subdetector getSubdetector();
+ /**
+ * Does this Decoder support cell neighboring?
+ * @return True if Decoder supports neighbors; false if not.
+ */
public boolean supportsNeighbours();
+
+ /**
+ * Get the current cell's neighbors using default neighboring parameters (usually 1,1,1).
+ * @return The cell neighbors.
+ */
public long[] getNeighbourIDs();
+
+ /**
+ * Get the current cell's neighbors using fully specified neighboring parameters.
+ * @param deltaLayer The number of layers to neighbor (plus or minus).
+ * @param deltaTheta The number of cells in theta to neighbor (plus or minus).
+ * @param deltaPhi The number of cells in phi to neighbor (plus or minus).
+ * @return
+ */
public long[] getNeighbourIDs(int deltaLayer, int deltaTheta, int deltaPhi);
-}
+}
\ No newline at end of file
