org.eclipse.dawnsci.nexus.INexusDevice Maven / Gradle / Ivy
/*-
*******************************************************************************
* Copyright (c) 2011, 2016 Diamond Light Source Ltd.
* 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:
* Matthew Gerring - initial API and implementation and/or initial documentation
*******************************************************************************/
package org.eclipse.dawnsci.nexus;
import org.eclipse.dawnsci.nexus.builder.AbstractNexusObjectProvider;
import org.eclipse.dawnsci.nexus.builder.CustomNexusEntryModification;
import org.eclipse.dawnsci.nexus.builder.NexusObjectProvider;
import org.eclipse.january.dataset.IDataset;
import org.eclipse.january.dataset.LazyDataset;
/**
* Any device which can write NeXus should implement this interface.
*
* This can be done easily by extending {@link AbstractNexusObjectProvider}
*
* @param the type of nexus object to be created, a sub-interface of {@link NXobject},
* e.g. {@link NXdetector}
*
* @author Matthew Gerring, Matthew Dickie
*
*/
public interface INexusDevice {
/**
* Returns the object provider required for writing correct NeXus files.
*
*
* In this method you should prepare the {@link LazyDataset}s the device
* will fill during the scan. You can also write out static device metadata,
* which will not change during the scan.
*
*
* Use the methods on {@link NexusNodeFactory} to create a NeXus object which
* matches the device e.g. a {@link NXdetector}.
* final NXdetector detector = NexusNodeFactory.createNXdetector();
*
*
* On the detector object you can create {@link LazyDataset}s and keep
* references which you can later use during the scan to write data. e.g.
* imageData = detector.initializeLazyDataset(NXdetector.NX_DATA, info.getRank() + 2, Dataset.FLOAT64);
* You should also set chunking on the {@link LazyDataset}s you create e.g. imageData.setChunking(info.createChunk(detectorXSize, detectorYSize));.
*
* In this method you can also write static metadata such as the detector
* exposure e.g.
* detector.setField("exposure_time", model.getExposure());. Or
* static datasets such as the image axis data
* detector.setDataset("image_x_axis", DatasetFactory.createLinearSpace(minX, maxX, xPoints, Dataset.FLOAT64));
* For fields that are defined in the NXDL base class definition for the
* returned nexus object, a setXXX or setXXXScalar method may be used as
* appropriate, e.g. detector.setLocalName(DatasetFactory.createFromObject("my detector"));
* or detector.setLocalNameScalar("my detector");
*
* If this device is a 'metadata scannable', then the device should write
* its data at this point directly into the returned nexus object. This can be
* done with the {@link NXobject#setField(String, Object)} method, or the
* setXXXScalar methods for fields defined in the appropriate
* NXDL base class definition.
*
* @param info
* Information about the scan which can be useful when creating
* dataset e.g. info.getRank()
* @return The {@link NXobject} created using the nodeFactory
* to represent this device
* @throws NexusException if the nexus object could not be created for any reason
*/
NexusObjectProvider getNexusProvider(NexusScanInfo info) throws NexusException;
/**
* Returns an object that performs a custom modification to
* an {@link NXentry}.
*
* NOTE: Use this method with caution as it can be used to break the central
* design concept of the new Nexus writing framework, namely that the nexus framework itself
* knows where to put the nexus groups for devices and build any required {@link NXdata} groups.
* It is currently used by the new Nexus framework to partially support legacy GDA8 spring
* configurations, in particular the 'locationmap'.
*
* The nexus framework will call this method after {@link #createNexusObject(NexusNodeFactory, NexusScanInfo)},
* so this method create links to nodes created in that method if appropriate.
*
* The easiest way to implement this method is to make this object itself also implement
* {@link CustomNexusEntryModification}. This method can then be overridden to simply
* return this.
*
* @return a {@link CustomNexusEntryModification} that makes a custom modification,
* or null if this device should not make custom modifications
*/
default CustomNexusEntryModification getCustomNexusModification() {
return null;
}
}