PCL
FileFormatInstance.h
Go to the documentation of this file.
1 // ____ ______ __
2 // / __ \ / ____// /
3 // / /_/ // / / /
4 // / ____// /___ / /___ PixInsight Class Library
5 // /_/ \____//_____/ PCL 2.6.5
6 // ----------------------------------------------------------------------------
7 // pcl/FileFormatInstance.h - Released 2024-01-13T15:47:58Z
8 // ----------------------------------------------------------------------------
9 // This file is part of the PixInsight Class Library (PCL).
10 // PCL is a multiplatform C++ framework for development of PixInsight modules.
11 //
12 // Copyright (c) 2003-2024 Pleiades Astrophoto S.L. All Rights Reserved.
13 //
14 // Redistribution and use in both source and binary forms, with or without
15 // modification, is permitted provided that the following conditions are met:
16 //
17 // 1. All redistributions of source code must retain the above copyright
18 // notice, this list of conditions and the following disclaimer.
19 //
20 // 2. All redistributions in binary form must reproduce the above copyright
21 // notice, this list of conditions and the following disclaimer in the
22 // documentation and/or other materials provided with the distribution.
23 //
24 // 3. Neither the names "PixInsight" and "Pleiades Astrophoto", nor the names
25 // of their contributors, may be used to endorse or promote products derived
26 // from this software without specific prior written permission. For written
27 // permission, please contact info@pixinsight.com.
28 //
29 // 4. All products derived from this software, in any form whatsoever, must
30 // reproduce the following acknowledgment in the end-user documentation
31 // and/or other materials provided with the product:
32 //
33 // "This product is based on software from the PixInsight project, developed
34 // by Pleiades Astrophoto and its contributors (https://pixinsight.com/)."
35 //
36 // Alternatively, if that is where third-party acknowledgments normally
37 // appear, this acknowledgment must be reproduced in the product itself.
38 //
39 // THIS SOFTWARE IS PROVIDED BY PLEIADES ASTROPHOTO AND ITS CONTRIBUTORS
40 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
41 // TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
42 // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL PLEIADES ASTROPHOTO OR ITS
43 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
44 // EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, BUSINESS
45 // INTERRUPTION; PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; AND LOSS OF USE,
46 // DATA OR PROFITS) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
47 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
48 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
49 // POSSIBILITY OF SUCH DAMAGE.
50 // ----------------------------------------------------------------------------
51 
52 #ifndef __PCL_FileFormatInstance_h
53 #define __PCL_FileFormatInstance_h
54 
56 
57 #ifndef __PCL_BUILDING_PIXINSIGHT_APPLICATION
58 
59 #include <pcl/Defs.h>
60 
61 #include <pcl/FITSHeaderKeyword.h>
62 #include <pcl/ImageDescription.h>
63 #include <pcl/ImageVariant.h>
64 #include <pcl/Property.h>
65 #include <pcl/UIObject.h>
66 
67 namespace pcl
68 {
69 
70 // ----------------------------------------------------------------------------
71 
72 class PCL_CLASS ColorFilterArray;
73 class PCL_CLASS DisplayFunction;
74 class PCL_CLASS FileFormat;
75 class PCL_CLASS ICCProfile;
76 
89 class PCL_CLASS FileFormatInstance : public UIObject
90 {
91 public:
92 
96  FileFormatInstance( const FileFormat& fmt );
97 
102  : UIObject( std::move( x ) )
103  {
104  }
105 
115  {
116  }
117 
122  {
123  Transfer( x );
124  return *this;
125  }
126 
134  void EnsureUnique() override
135  {
136  }
137 
143  static FileFormatInstance& Null();
144 
149  FileFormat Format() const;
150 
156  bool Close();
157 
161  bool IsOpen() const;
162 
168  String FilePath() const;
169 
170  // Reader functionality
171 
209  bool Open( ImageDescriptionArray& images,
210  const String& filePath, const IsoString& hints = IsoString() );
211 
212  bool Open( ImageDescriptionArray& images, const String& filePath, const IsoString::ustring_base& hints )
213  {
214  return Open( images, filePath, IsoString( hints ) );
215  }
216 
228  bool SelectImage( int index );
229 
238  int SelectedImageIndex() const;
239 
252  const void* FormatSpecificData() const;
253 
263  String ImageFormatInfo() const;
264 
275  bool ReadICCProfile( ICCProfile& icc );
276 
292  bool ReadRGBWorkingSpace( RGBColorSystem& rgbws );
293 
309  bool ReadDisplayFunction( DisplayFunction& df );
310 
325  bool ReadColorFilterArray( ColorFilterArray& cfa );
326 
337  bool ReadThumbnail( UInt8Image& thumbnail );
338 
350  bool ReadFITSKeywords( FITSKeywordArray& keywords );
351 
369  PropertyDescriptionArray PropertyDescriptions();
370 
388  bool HasProperty( const IsoString& property )
389  {
390  return PropertyDescriptions().Contains( property );
391  }
392 
393  bool HasProperty( const IsoString::ustring_base& property )
394  {
395  return HasProperty( IsoString( property ) );
396  }
397 
414  {
415  PropertyDescriptionArray properties = PropertyDescriptions();
416  PropertyDescriptionArray::const_iterator i = properties.Search( property );
417  if ( i == properties.End() )
418  return pcl::PropertyDescription();
419  return *i;
420  }
421 
423  {
424  return PropertyDescription( IsoString( property ) );
425  }
426 
443  Variant ReadProperty( const IsoString& property );
444 
445  Variant ReadProperty( const IsoString::ustring_base& property )
446  {
447  return ReadProperty( IsoString( property ) );
448  }
449 
465  PropertyArray ReadProperties();
466 
479  PropertyDescriptionArray ImagePropertyDescriptions();
480 
493  bool HasImageProperty( const IsoString& property )
494  {
495  return ImagePropertyDescriptions().Contains( property );
496  }
497 
498  bool HasImageProperty( const IsoString::ustring_base& property )
499  {
500  return HasImageProperty( IsoString( property ) );
501  }
502 
514  {
515  PropertyDescriptionArray properties = ImagePropertyDescriptions();
516  PropertyDescriptionArray::const_iterator i = properties.Search( property );
517  if ( i == properties.End() )
518  return pcl::PropertyDescription();
519  return *i;
520  }
521 
522  pcl::PropertyDescription ImagePropertyDescription( const IsoString::ustring_base& property )
523  {
524  return ImagePropertyDescription( IsoString( property ) );
525  }
526 
538  Variant ReadImageProperty( const IsoString& property );
539 
540  Variant ReadImageProperty( const IsoString::ustring_base& property )
541  {
542  return ReadImageProperty( IsoString( property ) );
543  }
544 
555  PropertyArray ReadImageProperties();
556 
561  bool ReadImage( FImage& image );
562 
567  bool ReadImage( DImage& image );
568 
573  bool ReadImage( UInt8Image& image );
574 
579  bool ReadImage( UInt16Image& image );
580 
585  bool ReadImage( UInt32Image& image );
586 
593  bool ReadImage( ImageVariant& image )
594  {
595  if ( image )
596  if ( !image.IsComplexSample() )
597  if ( image.IsFloatSample() )
598  switch ( image.BitsPerSample() )
599  {
600  case 32: return ReadImage( static_cast<pcl::Image&>( *image ) );
601  case 64: return ReadImage( static_cast<pcl::DImage&>( *image ) );
602  }
603  else
604  switch ( image.BitsPerSample() )
605  {
606  case 8: return ReadImage( static_cast<pcl::UInt8Image&>( *image ) );
607  case 16: return ReadImage( static_cast<pcl::UInt16Image&>( *image ) );
608  case 32: return ReadImage( static_cast<pcl::UInt32Image&>( *image ) );
609  }
610  return false;
611  }
612 
622  bool CanReadIncrementally() const;
623 
651  bool ReadSamples( FImage::sample* buffer, int startRow, int rowCount, int channel );
652 
660  bool ReadSamples( DImage::sample* buffer, int startRow, int rowCount, int channel );
661 
669  bool ReadSamples( UInt8Image::sample* buffer, int startRow, int rowCount, int channel );
670 
678  bool ReadSamples( UInt16Image::sample* buffer, int startRow, int rowCount, int channel );
679 
687  bool ReadSamples( UInt32Image::sample* buffer, int startRow, int rowCount, int channel );
688 
697  bool WasInexactRead() const;
698 
699  // Writer functionality
700 
732  bool QueryOptions( Array<ImageOptions>& options, Array<const void*>& formatOptions );
733 
762  bool Create( const String& filePath, const IsoString& hints = IsoString(), int numberOfImages = 1 );
763 
764  bool Create( const String& filePath, const IsoString::ustring_base& hints, int numberOfImages = 1 )
765  {
766  return Create( filePath, IsoString( hints ), numberOfImages );
767  }
768 
779  bool SetId( const IsoString& id );
780 
781  bool SetId( const IsoString::ustring_base& id )
782  {
783  return SetId( IsoString( id ) );
784  }
785 
796  bool SetOptions( const ImageOptions& options );
797 
826  bool SetFormatSpecificData( const void* data );
827 
835  bool WriteICCProfile( const ICCProfile& icc );
836 
847  bool WriteRGBWorkingSpace( const RGBColorSystem& rgbws );
848 
859  bool WriteDisplayFunction( const DisplayFunction& df );
860 
871  bool WriteColorFilterArray( const ColorFilterArray& cfa );
872 
880  bool WriteThumbnail( const UInt8Image& image );
881 
899  bool WriteProperty( const IsoString& property, const Variant& value );
900 
901  bool WriteProperty( const IsoString::ustring_base& property, const Variant& value )
902  {
903  return WriteProperty( IsoString( property ), value );
904  }
905 
913  bool WriteProperty( const Property& property )
914  {
915  return WriteProperty( property.Id(), property.Value() );
916  }
917 
932  bool WriteProperties( const PropertyArray& properties );
933 
948  bool WriteImageProperty( const IsoString& property, const Variant& value );
949 
950  bool WriteImageProperty( const IsoString::ustring_base& property, const Variant& value )
951  {
952  return WriteImageProperty( IsoString( property ), value );
953  }
954 
963  bool WriteImageProperty( const Property& property )
964  {
965  return WriteImageProperty( property.Id(), property.Value() );
966  }
967 
978  bool WriteImageProperties( const PropertyArray& properties );
979 
987  bool WriteFITSKeywords( const FITSKeywordArray& keywords );
988 
993  bool WriteImage( const FImage& image );
994 
999  bool WriteImage( const DImage& image );
1000 
1005  bool WriteImage( const UInt8Image& image );
1006 
1011  bool WriteImage( const UInt16Image& image );
1012 
1017  bool WriteImage( const UInt32Image& image );
1018 
1025  bool WriteImage( const ImageVariant& image )
1026  {
1027  if ( image )
1028  if ( !image.IsComplexSample() )
1029  if ( image.IsFloatSample() )
1030  switch ( image.BitsPerSample() )
1031  {
1032  case 32: return WriteImage( static_cast<const pcl::Image&>( *image ) );
1033  case 64: return WriteImage( static_cast<const pcl::DImage&>( *image ) );
1034  }
1035  else
1036  switch ( image.BitsPerSample() )
1037  {
1038  case 8: return WriteImage( static_cast<const pcl::UInt8Image&>( *image ) );
1039  case 16: return WriteImage( static_cast<const pcl::UInt16Image&>( *image ) );
1040  case 32: return WriteImage( static_cast<const pcl::UInt32Image&>( *image ) );
1041  }
1042  return false;
1043  }
1044 
1054  bool CanWriteIncrementally() const;
1055 
1071  bool CreateImage( const ImageInfo& info );
1072 
1082  bool CloseImage();
1083 
1112  bool WriteSamples( const FImage::sample* buffer, int startRow, int rowCount, int channel );
1113 
1121  bool WriteSamples( const DImage::sample* buffer, int startRow, int rowCount, int channel );
1122 
1130  bool WriteSamples( const UInt8Image::sample* buffer, int startRow, int rowCount, int channel );
1131 
1139  bool WriteSamples( const UInt16Image::sample* buffer, int startRow, int rowCount, int channel );
1140 
1148  bool WriteSamples( const UInt32Image::sample* buffer, int startRow, int rowCount, int channel );
1149 
1158  bool WasLossyWrite() const;
1159 
1160 private:
1161 
1162  FileFormatInstance( void* h ) : UIObject( h )
1163  {
1164  }
1165 
1166  void* CloneHandle() const override;
1167 
1168  friend class FileFormatInstancePrivate;
1169 };
1170 
1171 // ----------------------------------------------------------------------------
1172 
1173 } // pcl
1174 
1175 #endif // __PCL_BUILDING_PIXINSIGHT_APPLICATION
1176 
1177 #endif // __PCL_FileFormatInstance_h
1178 
1179 // ----------------------------------------------------------------------------
1180 // EOF pcl/FileFormatInstance.h - Released 2024-01-13T15:47:58Z
pcl
PCL root namespace.
Definition: AbstractImage.h:76
pcl::FileFormatInstance::WriteImage
bool WriteImage(const ImageVariant &image)
Definition: FileFormatInstance.h:1025
pcl::FileFormatInstance
High-level interface to an image file format instance.
Definition: FileFormatInstance.h:89
UInt16Image
16-bit unsigned integer image.
pcl::Property::Id
const identifier_type & Id() const
Definition: Property.h:161
pcl::Array::const_iterator
const T * const_iterator
Definition: Array.h:117
pcl::String
Unicode (UTF-16) string.
Definition: String.h:8112
pcl::Variant
Acts like a union to store instances of different data types.
Definition: Variant.h:331
pcl::ImageVariant::IsFloatSample
bool IsFloatSample() const noexcept
Definition: ImageVariant.h:441
pcl::Array::End
iterator End()
Definition: Array.h:451
pcl::FileFormatInstance::ImagePropertyDescription
pcl::PropertyDescription ImagePropertyDescription(const IsoString &property)
Definition: FileFormatInstance.h:513
pcl::IsoString
Eight-bit string (ISO/IEC-8859-1 or UTF-8 string)
Definition: String.h:5424
PropertyArray
Dynamic array of Property objects.
pcl::FileFormatInstance::FileFormatInstance
FileFormatInstance(FileFormatInstance &&x)
Definition: FileFormatInstance.h:101
FITSKeywordArray
Dynamic array of FITS header keywords.
pcl::UIObject
Root base class for all user interface objects.
Definition: UIObject.h:94
UInt8Image
8-bit unsigned integer image.
pcl::Property
An identifier-value association.
Definition: Property.h:78
pcl::FileFormatInstance::HasProperty
bool HasProperty(const IsoString &property)
Definition: FileFormatInstance.h:388
pcl::IsoString::ustring_base
GenericString< char16_type, CharTraits, PCL_STRING_ALLOCATOR > ustring_base
Definition: String.h:5488
pcl::FileFormatInstance::WriteImageProperty
bool WriteImageProperty(const Property &property)
Definition: FileFormatInstance.h:963
pcl::PropertyDescription
A structure to describe a data property.
Definition: PropertyDescription.h:77
pcl::FileFormatInstance::PropertyDescription
pcl::PropertyDescription PropertyDescription(const IsoString &property)
Definition: FileFormatInstance.h:413
pcl::GenericString< char16_type, CharTraits, PCL_STRING_ALLOCATOR >
pcl::FileFormatInstance::WriteProperty
bool WriteProperty(const Property &property)
Definition: FileFormatInstance.h:913
pcl::FileFormatInstance::~FileFormatInstance
~FileFormatInstance() override
Definition: FileFormatInstance.h:114
pcl::FileFormatInstance::HasImageProperty
bool HasImageProperty(const IsoString &property)
Definition: FileFormatInstance.h:493
pcl::GenericImage::sample
typename pixel_traits::sample sample
Definition: Image.h:305
Property.h
UInt32Image
32-bit unsigned integer image.
pcl::FileFormatInstance::ReadImage
bool ReadImage(ImageVariant &image)
Definition: FileFormatInstance.h:593
pcl::Array< ImageDescription >
PropertyDescriptionArray
Dynamic array of PropertyDescription structures.
FITSHeaderKeyword.h
ImageDescription.h
UIObject.h
pcl::ImageInfo
A simple structure to hold basic information about images.
Definition: ImageInfo.h:71
pcl::FileFormatInstance::EnsureUnique
void EnsureUnique() override
Definition: FileFormatInstance.h:134
pcl::ImageVariant::IsComplexSample
bool IsComplexSample() const noexcept
Definition: ImageVariant.h:449
DImage
64-bit floating point real image.
pcl::Property::Value
const value_type & Value() const
Definition: Property.h:169
pcl::Array::Search
iterator Search(const T &v) const noexcept
Definition: Array.h:1512
FImage
32-bit floating point real image.
pcl::ImageVariant
Acts like a union for all types of images in PCL, with optional class-wide ownership of transported i...
Definition: ImageVariant.h:321
Defs.h
pcl::FileFormat
High-level interface to an installed image file format.
Definition: FileFormat.h:97
pcl::ImageVariant::BitsPerSample
int BitsPerSample() const noexcept
Definition: ImageVariant.h:458
ImageVariant.h
pcl::GenericImage
Implements a generic, two-dimensional, shared or local image.
Definition: Image.h:277