Package org.eclipse.scanning.api.points

Interface IPosition

All Known Implementing Classes:
AbstractPosition, MapPosition, Point, Scalar, StaticPosition
public interface IPosition
A position is a location of one or more values. It is used to group scannables when moving to a position by level.

For instance a group of scannables which need to be at a certain location. For example at the start of a scan or for a scan datapoint.

NOTE: An object is available using IDeviceService.createPositioner() called IPositioner which can move scannables to a given position by level.

Implementations of this class should be immutable where possible. Where this is not possible they should not be modified once they have been fully initialized.

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final uk.ac.diamond.daq.util.logging.deprecation.DeprecationLogger
    logger
    Deprecated, for removal: This API element is subject to removal in a future version.

  • Method Summary

    Modifier and Type
    Method
    Description
    IPosition
    compound(IPosition parent)
    Creates a composite position with the values of this position and the values of the passed in position.
    Object
    get(String name)
    The value of a named position.
    List<List<String>>
    getDimensionNames()
    This method makes dimensionNames if they are null.
    default double
    getDouble(String name)
    Returns the value as a double, equivalent to ((Number)get(name)).doubleValue() Available for convenience.
    double
    getExposureTime()
    Get the exposure time to be used for the detector, in seconds.
    int
    getIndex(int dimension)
    Get the data index of this point for a given scan dimension.
    int
    getIndex(String name)
    Get the index of the data for instance in a scan of temperature from 290 to 300 step 1, the indices will be 0-10.
    default Map<String,Integer>
    getIndices()
    It is not required of an IPosition to provide getIndices() but it may do so to avoid a new map being built up.
    List<String>
    getNames()
    The names of all the scalars set for this position.
    int
    getScanRank()
    Most scans have rank 1 event though they move more motors line a line scan or a spiral scan.
    default int
    getStepIndex()
    The step where the position was in a scan, if it is a position being generated from a scan.
    default double
    getValue(String name)
    Deprecated, for removal: This API element is subject to removal in a future version.
    this method has a misleading name, use getDouble(String) instead if you know you want a double, or get(String) if you want to get the value whatever its type.
    default Map<String,Object>
    getValues()
    It is not required of an IPosition to provide getValues() but it may do so to avoid a new map being built up.
    void
    setDimensionNames(List<List<String>> dimensionNames)
     
    void
    setExposureTime(double time)
    Call to set the exposure time for the position Exposure time is normally set before a 2D scan however for energy scans bands of different energies can be created each with a different step increment and potentially different exposure time.
    default void
    setStepIndex(int step)
    The step where the position was in a scan, if it is a position being generated from a scan.
    int
    size()
    The number of named scalars in this position

  • Field Details

    • logger

      @Deprecated(since="GDA 9.28", forRemoval=true) static final uk.ac.diamond.daq.util.logging.deprecation.DeprecationLogger logger
      Deprecated, for removal: This API element is subject to removal in a future version.

  • Method Details

    • size

      int size()
      The number of named scalars in this position
      Returns:
      number of scalars

    • getNames

      List<String> getNames()
      The names of all the scalars set for this position. For instance 'x' and 'y' for a map or 'Temperature' Note to implementers: should never return null
      Returns:
      name of scalars

    • getIndex

      int getIndex(int dimension)
      Get the data index of this point for a given scan dimension. For instance
      Parameters:
      dimension -
      Returns:
      data index for the given dimension index

    • getIndex

      int getIndex(String name)
      Get the index of the data for instance in a scan of temperature from 290 to 300 step 1, the indices will be 0-10. If one dimension has more than one motor with it, for instance x and y in a line scan, both getIndex("x") and getIndex("y") return the same value.
      Returns:
      data index for given axis name

    • get

      Object get(String name)
      The value of a named position. For instance get("X") to return the value of the X IScannable double.
      Parameters:
      name -
      Returns:
      value for the given axis name

    • getValue

      @Deprecated(since="GDA 9.29", forRemoval=true) default double getValue(String name)
      Deprecated, for removal: This API element is subject to removal in a future version.
      this method has a misleading name, use getDouble(String) instead if you know you want a double, or get(String) if you want to get the value whatever its type.
      Returns the value as a double, equivalent to ((Number)get(name)).doubleValue() Available for convenience. If the value is not a Number, a ClassCastException is thrown.
      Parameters:
      name -
      Returns:
      value for the given axis name as a double
      Throws:
      ClassCastException - if the value is not a Number

    • getDouble

      default double getDouble(String name)
      Returns the value as a double, equivalent to ((Number)get(name)).doubleValue() Available for convenience. If the value is not a Number, a ClassCastException is thrown.
      Parameters:
      name -
      Returns:
      value for the given axis name as a double
      Throws:
      ClassCastException - if the value is not a Number

    • compound

      IPosition compound(IPosition parent)
      Creates a composite position with the values of this position and the values of the passed in position. The passed in position is assumed to be the parent in the scan.

      NOTE The scan names are not calculated on the call to compound because maintaining the list of names in each dimension is inefficient to calculate for each point (they do not change). Instead the names are created once and set into the position using setDimensionNames(...) available on abstract position.

      Parameters:
      parent -
      Returns:
      the compounded position

    • getStepIndex

      default int getStepIndex()
      The step where the position was in a scan, if it is a position being generated from a scan. If not the value will be -1
      Returns:
      position in a scan or -1

    • setStepIndex

      default void setStepIndex(int step)
      The step where the position was in a scan, if it is a position being generated from a scan. If not the value will be -1
      Parameters:
      step -

    • getScanRank

      int getScanRank()
      Most scans have rank 1 event though they move more motors line a line scan or a spiral scan. As scans are aggregated these scan dimensions sum together. Some scans start out as having two dimensions like a grid or raster scan.
      Returns:
      scan rank

    • getValues

      default Map<String,Object> getValues()
      It is not required of an IPosition to provide getValues() but it may do so to avoid a new map being built up. Implement this method to ensure that your position runs faster. The default implementation works.
      Returns:
      values as a String to Object Map
      See Also:

    • getIndices

      default Map<String,Integer> getIndices()
      It is not required of an IPosition to provide getIndices() but it may do so to avoid a new map being built up. Implement this method to ensure that your position runs faster. The default implementation works.
      Returns:
      map of indices for axis name
      See Also:

    • getExposureTime

      double getExposureTime()
      Get the exposure time to be used for the detector, in seconds. Exposure time is normally set before a 2D scan however for energy scans bands of different energies can be created each with a different step increment and potentially different exposure time. It is not possible to set different detectors with different exposure times during the scan; that would require a map here. Anthony Hull and I decided this should be part of a future change, when required.
      Returns:
      the exposure time in seconds. Can be zero but not negative. If zero then no change is made to the detector's exposure time setting.

    • setExposureTime

      void setExposureTime(double time)
      Call to set the exposure time for the position Exposure time is normally set before a 2D scan however for energy scans bands of different energies can be created each with a different step increment and potentially different exposure time. It is not possible to set different detectors with different exposure times during the scan with the mechanism. This can achieved in a malcolm scan by setting IDetectorModel.setExposureTime(double) for each detector in the IMalcolmModel.
      Parameters:
      time - exposure time.

    • getDimensionNames

      List<List<String>> getDimensionNames()
      This method makes dimensionNames if they are null. Dimensions may contain 1-N axes, e.g. when a Mapping scan is bounded by a 2d region of interest.
      Returns:
      axis names for each dimension

    • setDimensionNames

      void setDimensionNames(List<List<String>> dimensionNames)