Hi Rob,
Format hints are fully supported by the FileFormat and FileFormatInstance JavaScript objects, which were introduced in PixInsight 1.7.0. I decided not to comment on these new objects until now because the implementation is still slightly incomplete, but I'll do briefly now.
These objects are the JavaScript counterparts of the
pcl::FileFormat and
pcl::FileFormatInstance C++ classes. On the PCL reference documentation links given you'll find complete information.
FileFormat gives you access to an installed file format such as FITS, TIFF, JPEG, etc. You can create a FileFormat object with the constructor:
new FileFormat( String nameExtOrMime[, Boolean toRead=false[, Boolean toWrite=false]] )For example, this line gives you access to the DSLR_RAW module:
var F = new FileFormat( ".cr2", true/*toRead*/ );Once you have access to an installed file format you can instantiate it with FileFormatInstance. A file format instance is an abstraction that allows you to work with existing or newly created image files of a particular format. The constructor is:
new FileFormatInstance( FileFormat format )and the relevant functions to open and create/write a file:
Array FileFormatInstance.open( String filePath[, String hints] )
Boolean FileFormatInstance.readImage( Image )
Boolean FileFormatInstance.create( String filePath[, String hints[, int numberOfImages=1]] )
Boolean FileFormatInstance.createImage( ImageDescription d )
Boolean FileFormatInstance.writeImage( Image )
Boolean FileFormatInstance.close()For example, you can open a Canon CR2 file in this way:
var f = new FileFormatInstance( F );
var a = f.open( "/path/to/foo.cr2" );FileFormatInstance.open() returns an array of ImageDescription objects. Each object in the array describes an image stored in the file. Some formats (FITS) support multiple images stored in a single file but this is not the case of DSLR_RAW, so the returned array in this case will have only an element. This function supports file format hints. For example:
var f = new FileFormatInstance( F );
var a = f.open( "/path/to/foo.cr2", "raw" );
if ( a.length == 0 )
throw new Error( "File access error" );would open the foo.cr2 file as a Bayer RGB image without interpolation and no black point correction, irrespective of the current DSLR_RAW settings. Once you have opened the file you can read an image with code such as:
Image img;
if ( !f.readImage( img ) )
throw new Error( "File read error" );
f.close();File creation and storage is also rather simple. Following the same example, suppose you want to write the CR2 image as a floating point FITS file with top-to-bottom/left-to-right orientation, irrespective of the current FITS settings:
var F = new FileFormat( ".fit", false/*toRead*/, true/*toWrite*/ );
var f = new FileFormatInstance( F );
if ( !f.create( "/path/to/bar.fit", "up-bottom" ) )
throw new Error( "File creation error" );
var d = new ImageDescription;
d.bitsPerSample = 32;
d.ieeefpSampleFormat = true;
if ( !f.createImage( d ) )
throw new Error( "Image creation error" );
if ( !f.writeImage( img ) )
throw new Error( "File write error" );
f.close();Let me know if this helps.
