1 package org.lcsim.detector;
2
3 import hep.physics.vec.Hep3Vector;
4
5 import java.util.List;
6
7 import org.lcsim.detector.identifier.Identifiable;
8 import org.lcsim.detector.identifier.IIdentifier;
9 import org.lcsim.detector.identifier.IIdentifierHelper;
10
11 /**
12 * A class to represent a node in the detector hierarchy, based on Gaudi's IDetectorElement interface. The concept of DetectorElement is more abstract than physical geometry, as it may simply be a
13 * container for other DetectorElements and need not have a physical representation in the geometry tree.
14 *
15 * @see IDetectorElementStore
16 * @see IDetectorElementContainer
17 * @see IGeometryInfo
18 * @see Identifiable
19 * @see IIdentifier
20 * @see IParameters
21 * @see IReadout
22 *
23 * @author jeremym
24 * @author tknelson
25 * @version $Id: IDetectorElement.java,v 1.25 2009/03/03 21:07:24 jeremy Exp $
26 */
27 public interface IDetectorElement extends Identifiable {
28 /**
29 * Get the geometric information for this node, including the volume center position and global and local transformations.
30 *
31 * @return An IGeometryInfo object with geometry information.
32 */
33 public IGeometryInfo getGeometry();
34
35 /**
36 * Get the parent element of this node. The top-level <code>DetectorElement</code> has no parent.
37 *
38 * @return This node's parent or <code>null</code> if the DetectorElement has no parent.
39 */
40 public IDetectorElement getParent();
41
42 /**
43 * Get a container with the DetectorElement's children.
44 *
45 * @return An IDetectorElementContainer containing this DE's children. This container will be empty if there are no children.
46 */
47 public IDetectorElementContainer getChildren();
48
49 /**
50 * True if the DetectorElement has children.
51 *
52 * @return True if has children, else False.
53 */
54 public boolean hasChildren();
55
56 /**
57 * Get the name of this DetectorElement.
58 *
59 * @return The name this DetectorElement.
60 */
61 public String getName();
62
63 /**
64 * Set the identifier of this DE.
65 *
66 * @param id
67 */
68 public void setIdentifier(IIdentifier id);
69
70 /**
71 * Get the identifier of this DE.
72 *
73 * @return The unique identifier of this DetectorElement.
74 */
75 public IIdentifier getIdentifier();
76
77 public IIdentifierHelper getIdentifierHelper();
78
79 /**
80 * Set the parent DetectorElement. This method also calls addChild on the parent.
81 *
82 * @param parent The parent DetectorElement.
83 */
84 public void setParent(IDetectorElement parent);
85
86 /**
87 * @return True if {@link IGeometryInfo} has been created; False if {@link IGeometryInfo} is <code>null</code>.
88 */
89 public boolean hasGeometryInfo();
90
91 /**
92 * Locate the deepest DetectorElement containing a global point starting with this DetectorElement and traversing into its children.
93 *
94 * This method can be used from {@link org.lcsim.geometry.Detector} to find the deepest node within the complete detector.
95 *
96 * This method is not on {@link GeometryInfo}, because a DetectorElement is allowed to have a <code>null</code> GeometryInfo if it is a simple container without a geometry path, i.e. a ghost
97 * volume.
98 *
99 * @return The deepest IDetectorElement containing globalPoint or <code>null</code> if point is not contained within this DetectorElement or its children.
100 */
101 public IDetectorElement findDetectorElement(Hep3Vector globalPoint);
102
103 /**
104 * Locate a child detector element by {@link IIdentifier}.
105 * @param id The <code>IIdentifier</code> of the <code>DetectorElement</code>.
106 * @return The matching <code>IDetectorElement</code> to the ID.
107 */
108 public IDetectorElementContainer findDetectorElement(IIdentifier id);
109
110 /**
111 * Locate a child detector element given a slash-separated list of DetectorElement names.
112 * @param pathString
113 * @return
114 */
115 public IDetectorElement findDetectorElement(String pathString);
116
117 /**
118 * Locate a child detector element given an ordered list of DetectorElement names.
119 * @param path
120 * @return
121 */
122 public IDetectorElement findDetectorElement(String[] path);
123
124 /**
125 * Get the readout associated with this DetectorElement, or <code>null</code> if the DetectorElement has no associated readout.
126 *
127 * @see org.lcsim.detector.IReadout
128 * @see org.lcsim.detector.Readout
129 *
130 * @return Associated IReadout object or <code>null</code> if Readout has been assigned to this DetectorElement.
131 */
132 public IReadout getReadout();
133
134 /**
135 * True if this DetectorElement has an {@link IReadout}; False if the {@link IReadout} is <code>null</code>.
136 *
137 * @return True if this DetectorElement has a Readout; False if there is no Readout.
138 */
139 public boolean hasReadout();
140
141 /**
142 * The named parameters associated to this instance.
143 *
144 * @see org.lcsim.detector.IParameters
145 *
146 * @return An IParameters object containing the DetectorElement's named parameter set.
147 */
148 public IParameters getParameters();
149
150 /**
151 * A list of parents from the top to this one. The first member of the list will be the top {@link IDetectorElement} in the hierarchy. The last memory of the list will be this
152 * {@link IDetectorElement}.
153 *
154 * @see IDetectorElementContainer
155 *
156 * @return A list of ancestors from the top to this node.
157 */
158 public IDetectorElementContainer getAncestry();
159
160 /**
161 * True if the DetectorElement is an ancestor of this one.
162 */
163 public boolean isAncestor(IDetectorElement de);
164
165 /**
166 * Clear the {@link IReadout} of this {@link DetectorElement} and recursively visit and clear the children..
167 *
168 * @see IReadout
169 * @see Readout
170 */
171 public void clearReadouts();
172
173 /**
174 * True if the DetectorElement is a descendant of this one.
175 *
176 * @param de A DetectorElement to search for in descendants.
177 * @see IDetectorElement
178 * @see IDetectorElementContainer
179 * @return True if DetectorElement is a descendant of this one.
180 */
181 public boolean isDescendant(IDetectorElement de);
182
183 /**
184 * Recursive pre-order tree traversal of this {@link IDetectorElement}.
185 * @param visitor A visitor interface to perform some action on the node.
186 */
187 public void traverseDescendantsPreOrder(IDetectorElementVisitor visitor);
188
189 /**
190 * Recrusive post-order tree traversal of this {@link IDetectorElement}.
191 * @param visitor A visitor interface to perform some action on the node.
192 */
193 public void traverseDescendantsPostOrder(IDetectorElementVisitor visitor);
194
195 /**
196 * Visit this and ancestors.
197 *
198 * @param visitor
199 */
200 public void traverseAncestors(IDetectorElementVisitor visitor);
201
202 /**
203 * Find ancestors matching a class.
204 *
205 * @param klass Class to match.
206 */
207 public <T extends IDetectorElement> List<T> findAncestors(Class<T> klass);
208
209 /**
210 * Find descendants matching a class.
211 *
212 * @param klass The class of the descendant DetectorElement.
213 * @return Get a list of descendants with matching class.
214 */
215 public <T extends IDetectorElement> List<T> findDescendants(Class<T> klass);
216
217 /**
218 * True if the DetectorElement's PhysicalVolume is flagged as sensitive. False if the PhysicalVolume is not sensitive or the DetectorElement has no associated geometry.
219 * @return True if sensitive; false if not sensitive.
220 */
221 public boolean isSensitive();
222
223 /**
224 * This method should be called externally to perform initialization after all child elements have been added.
225 */
226 public void initialize();
227 }