Programming Reference for VirtualLab Fusion  2026.1
Loading...
Searching...
No Matches
VL_Files Class Reference

This class provides methods for the import and export of fields to bitmaps, text files, or bitmap animations and access to the Microsoft Windows file system. More...

Static Public Member Functions

static Bitmap CalculateBitmapFromChromaticFieldsSet2D (ChromaticFieldsSet cfs, double brightnessFactor, out bool noVisibleWavelength, bool interpolated=true, Size? numberOfPixels=null, PhysicalValueRange? xRange=null, PhysicalValueRange? yRange=null)
 Static conversion method for creating a bitmap from a 2D Chromatic Fields Set.
 
static Bitmap CalculateBitmapFromDataArray2D (DataArray2D dataArray, int subsetIndex, FieldQuantity fieldQuantity, bool interpolated=true, Size? numberOfPixels=null, PhysicalValueRange? xRange=null, PhysicalValueRange? yRange=null, double minValue=double.NaN, double maxValue=double.NaN, ColorLookUpTableForDataView2D? colorTable=null, Color? colorForUndefined=null, double relativeThresholdForPhaseArtifacts=0)
 Static public conversion method for creating a bitmap from a 2D Data Array.
 
static IDocument ImportBitmap (string fileName)
 Import of a bitmap file. The document type will be determined automatically: An RGB image will be imported as HarmonicFieldsSet. A gray-scale or indexed image will be imported as DataArray.
 
static ComplexAmplitude ImportGrayScaleBitmap (string fileName, double minimumValue=0, double maximumValue=1, FieldQuantity fieldQuantity=FieldQuantity.RealPart, PrecisionMode precision=PrecisionMode.Double, double? wavelength=null)
 Imports the values of a grayscale bitmap (24 bit RGB or 16 bit gray scale) into a ComplexAmplitude. The sampling distance is calculated from the dpi values of the bitmap.
 
static ? ChromaticFieldsSet ImportTextFileIntoChromaticFieldsSet (string fileName, double wavelength, ChromaticFieldsSetType type=ChromaticFieldsSetType.Unspecified, double samplingDistanceX=1, double samplingDistanceY=1, string commentIndicator="#", string columnSeparator=" ", string decimalSeparator=".", string groupSeparator="", int firstRow=-1, int lastRow=-1, int numberOfCharactersToSkip=0, bool decreasingXCoordinates=false, bool decreasingYCoordinates=false)
 Imports a text file into a ChromaticFieldsSet object.
 
static ? ChromaticFieldsSet_1D ImportTextFileIntoChromaticFieldsSet1D (string fileName, List< double > wavelengths, ChromaticFieldsSetType type=ChromaticFieldsSetType.Unspecified, bool coordinatesAreCodedInData=false, double samplingDistance=1, string commentIndicator="#", string columnSeparator=" ", string decimalSeparator=".", string groupSeparator="", int firstRow=-1, int lastRow=-1, int numberOfCharactersToSkip=0, bool expectDataInColumns=true, bool decreasingCoordinates=false)
 Imports a text file into a ChromaticFieldsSet_1D object.
 
static ? ComplexField ImportTextFileIntoComplexField (string fileName, bool expectComplexValues, int firstRow, int lastRow, int numberOfCharactersToSkip, string commentIndicator, string columnSeparator, string decimalSeparator, string groupSeparator, out List<(bool is1D, bool? isGridless, bool? isEquidistant, bool? dataInColumns, int noOfSubsets)> possibleCombinations)
 Imports a text file into a ComplexField object.
 
static ? DataArrayBase ImportTextFileIntoDataArray (string fileName, bool expectComplexValues=false, bool coordinatesAreCodedInData=false, double samplingDistanceX=1, double samplingDistanceY=1, string commentIndicator="#", string columnSeparator=" ", string decimalSeparator=".", string groupSeparator="", int firstRow=-1, int lastRow=-1, int numberOfCharactersToSkip=0, bool prefer2Dover1D=true, bool preferGriddedOverGridless=true, bool expect1DOrGridlessDataInColumns=true, bool decreasingXCoordinates=false, bool decreasingYCoordinates=false, PhysicalMeaningType typeOfDA=PhysicalMeaningType.None)
 Imports a text file into a DataArray object.
 
static ? ComplexAmplitude ImportTextFileIntoHarmonicField (string fileName, double wavelength, bool expectComplexValues=false, string commentIndicator="#", string columnSeparator=" ", string decimalSeparator=".", string groupSeparator="", int firstRow=-1, int lastRow=-1, int numberOfCharactersToSkip=0)
 Imports a text file into a HarmonicField object.
 
static ComplexAmplitude LoadField (string fileName)
 Loads a field from a file.
 
static HarmonicFieldsSet LoadFieldsSet (string fileName)
 Loads a fields set from a file.
 
static int NumberOfLines (string fileName)
 Returns the number of lines in the text file specified by fileName.
 
static void ProcessOpticalSetup (string fileNameOpticalSetup, string outputFolder, string fileNameParameters="", PropagationEngine? simulationEngine=null, int? analyzerIndex=null, bool useSubfolder=false)
 Loads and simulates the given Optical Setup file.
 
static string ReadLine (string fileName, int lineNumber)
 Returns the nth line of the text file specified by fileName, where \(n\) equals the lineNumber. The first line of the file is line number 1. If the file does not exist or the specified line number is beyond the end of the file, the program using this method will be stopped unless the thrown exception is handled outside of this method.
 
static void SaveDocument (IDocument document, string fileName)
 Saves a document (e. g. a ComplexAmplitude or a HarmonicFieldsSet object) to the hard disc.
 
static void WriteLineToLogFile (string fileName, string message)
 Writes a string as a separate line to the end of the specified log file.
 
static void WriteToLogFile (string fileName, string message)
 Writes a string to the end of the specified log file. In contrast to the WriteLineToLogFile method, this method does not introduce a line break.
 

Detailed Description

This class provides methods for the import and export of fields to bitmaps, text files, or bitmap animations and access to the Microsoft Windows file system.

Member Function Documentation

◆ CalculateBitmapFromChromaticFieldsSet2D()

static Bitmap CalculateBitmapFromChromaticFieldsSet2D ( ChromaticFieldsSet cfs,
double brightnessFactor,
out bool noVisibleWavelength,
bool interpolated = true,
Size? numberOfPixels = null,
PhysicalValueRange? xRange = null,
PhysicalValueRange? yRange = null )
static

Static conversion method for creating a bitmap from a 2D Chromatic Fields Set.

Parameters
cfsChromatic fields set to create the bitmap from
brightnessFactorFactor to increase or decrease the brightness in the bitmap to be calculated. Too high brightness can lead to oversaturation.
noVisibleWavelengthOut parameter that indicates whether none of the wavelengths is in the range of visible wavelengths.
interpolatedIf this optional parameter is set to false, you see the original sampling points in the bitmap. Else an interpolation between neighbored sampling points is done.
numberOfPixelsNumber of pixels in the resulting bitmap. If this optional parameter is not specified, one pixel per sampling point is created.
xRangeOptional x-coordinate range of the Chromatic Fields Set to be displayed in the bitmap. Can be used to show only a part of the Chromatic Fields Set.
yRangeOptional y-coordinate range of the Chromatic Fields Set to be displayed in the bitmap. Can be used to show only a part of the Chromatic Fields Set.
Returns
The bitmap created from the Chromatic Fields Set.

◆ CalculateBitmapFromDataArray2D()

static Bitmap CalculateBitmapFromDataArray2D ( DataArray2D dataArray,
int subsetIndex,
FieldQuantity fieldQuantity,
bool interpolated = true,
Size? numberOfPixels = null,
PhysicalValueRange? xRange = null,
PhysicalValueRange? yRange = null,
double minValue = double::NaN,
double maxValue = double::NaN,
ColorLookUpTableForDataView2D? colorTable = null,
Color? colorForUndefined = null,
double relativeThresholdForPhaseArtifacts = 0 )
static

Static public conversion method for creating a bitmap from a 2D Data Array.

Parameters
dataArrayData Array to create the bitmap from
subsetIndexThe index of that data subset of the Data Array to be converted to the bitmap.
fieldQuantityThe field quantity to be converted to the bitmap.
interpolatedIf this optional parameter is set to false, you see the original sampling points in the bitmap. Else an interpolation between neighbored sampling points is done, using the interpolation methods (X and Y) of the data array.
numberOfPixelsNumber of pixels in the resulting bitmap. If this optional parameter is not specified, one pixel per sampling point is created.
xRangeOptional x-coordinate range of the Data Array to be displayed in the bitmap. Can be used to show only a part of the Chromatic Fields Set.
yRangeOptional y-coordinate range of the Data Array to be displayed in the bitmap. Can be used to show only a part of the Chromatic Fields Set.
minValueOptional minimum value to be mapped to a color. All values below will have the same color as this value.
maxValueOptional maximum value to be mapped to a color. All values above will have the same color as this value.
colorTableOptional color table for mapping double values to colors. By default the corresponding Global Option is used.
colorForUndefinedColor to be used for undefined values. By default the corresponding Global Option is used.
relativeThresholdForPhaseArtifactsThreshold for suppressing phase artifacts. If set to zero or below, no suppression will be done. Applies only if parameter fieldQuantity is set to FieldQuantity.Phase.
Returns
The bitmap created from the DataArray2D

◆ ImportBitmap()

static IDocument ImportBitmap ( string fileName)
static

Import of a bitmap file. The document type will be determined automatically: An RGB image will be imported as HarmonicFieldsSet. A gray-scale or indexed image will be imported as DataArray.

Parameters
fileNameFull path of image to be imported.
Returns
Either a HarmonicFieldsSet (for RGB image) or a DataArray (for indexed or gray-scale image).

◆ ImportGrayScaleBitmap()

static ComplexAmplitude ImportGrayScaleBitmap ( string fileName,
double minimumValue = 0,
double maximumValue = 1,
FieldQuantity fieldQuantity = FieldQuantity::RealPart,
PrecisionMode precision = PrecisionMode::Double,
double? wavelength = null )
static

Imports the values of a grayscale bitmap (24 bit RGB or 16 bit gray scale) into a ComplexAmplitude. The sampling distance is calculated from the dpi values of the bitmap.

Parameters
fileNameFile name of the bitmap to be imported.
minimumValueOptional minimum value, i.e. the value of black pixels. 0 by default.
maximumValueOptional maximum value, i.e. the value of white pixels. 1 by default.
fieldQuantityOptional field quantity. If not specified, the data is imported into the real part. If the field quantity is Imaginary Part or Phase, the resulting ComplexAmplitude will be complex-valued, otherwise it will be real-valued.
precisionOptional precision. No longer used.
wavelengthOptional wavelength. If you specify this value, a Harmonic Field instead of a Jones Matrix Transmission is generated.
Returns
A ComplexAmplitude with the imported data.

◆ ImportTextFileIntoChromaticFieldsSet()

static ? ChromaticFieldsSet ImportTextFileIntoChromaticFieldsSet ( string fileName,
double wavelength,
ChromaticFieldsSetType type = ChromaticFieldsSetType::Unspecified,
double samplingDistanceX = 1,
double samplingDistanceY = 1,
string commentIndicator = "#",
string columnSeparator = " ",
string decimalSeparator = ".",
string groupSeparator = "",
int firstRow = -1,
int lastRow = -1,
int numberOfCharactersToSkip = 0,
bool decreasingXCoordinates = false,
bool decreasingYCoordinates = false )
static

Imports a text file into a ChromaticFieldsSet object.

Parameters
fileNameThe full path of the text file to be imported.
wavelengthThe wavelength of the chromatic fields set to be created.
samplingDistanceXThe sampling distance to be used for the x-coordinates if the coordinates are not coded within the data.
samplingDistanceYThe sampling distance to be used for the y-coordinates if the coordinates are not coded within the data.
commentIndicatorThe character to be interpreted as comment indicator, preceding lines which are to be ignored.
columnSeparatorCharacter which separates columns in the file. Please note: All 'white-space' characters are interchangeable. This means, for example, providing a blank will work with tabulator-separated columns and vice versa.
decimalSeparatorCharacter which separates the integer part from the fractional part of the numbers in the file.
groupSeparatorCharacter which 'groups' three digits respectively, so it can be called 'thousands separator' as well. This parameter may be left empty, meaning that no group separator is used in the file.
firstRowThe first row to read from file. If set to -1, all lines will be processed.
lastRowThe last row to read from file. If set to -1, all lines will be processed.
numberOfCharactersToSkipIf greater than zero, this number of characters will be ignored at the beginning of each line.
decreasingXCoordinatesAre the actual x-coordinates to be interpreted as decreasing with increasing column-index?
decreasingYCoordinatesAre the actual y-coordinates to be interpreted as decreasing with increasing row-index?
typeThe type of object which is to be represented by the imported chromatic fields set.
Returns
The imported ChromaticFieldsSet.

◆ ImportTextFileIntoChromaticFieldsSet1D()

static ? ChromaticFieldsSet_1D ImportTextFileIntoChromaticFieldsSet1D ( string fileName,
List< double > wavelengths,
ChromaticFieldsSetType type = ChromaticFieldsSetType::Unspecified,
bool coordinatesAreCodedInData = false,
double samplingDistance = 1,
string commentIndicator = "#",
string columnSeparator = " ",
string decimalSeparator = ".",
string groupSeparator = "",
int firstRow = -1,
int lastRow = -1,
int numberOfCharactersToSkip = 0,
bool expectDataInColumns = true,
bool decreasingCoordinates = false )
static

Imports a text file into a ChromaticFieldsSet_1D object.

Parameters
fileNameThe full path of the text file to be imported.
wavelengthsThe wavelengths of the chromatic fields set to be created.
coordinatesAreCodedInDataAre the coordinates for all of the data points given in the text data (being the first column or row of values) as well?
samplingDistanceThe sampling distance to be used if the coordinates are not coded within the data.
commentIndicatorThe character to be interpreted as comment indicator, preceding lines which are to be ignored.
columnSeparatorCharacter which separates columns in the file. Please note: All 'white-space' characters are interchangeable. This means, for example, providing a blank will work with tabulator-separated columns and vice versa.
decimalSeparatorCharacter which separates the integer part from the fractional part of the numbers in the file.
groupSeparatorCharacter which 'groups' three digits respectively, so it can be called 'thousands separator' as well. This parameter may be left empty, meaning that no group separator is used in the file.
firstRowThe first row to read from file. If set to -1, all lines will be processed.
lastRowThe last row to read from file. If set to -1, all lines will be processed.
numberOfCharactersToSkipIf greater than zero, this number of characters will be ignored at the beginning of each line.
expectDataInColumnsSeveral data sets (corresponding to different wavelengths) can be in columns or in rows. Which option is preferred (column-wise = true vs. row-wise = false)?
decreasingCoordinatesAre the actual coordinates to be interpreted as decreasing with increasing column- (or row-) index?
typeThe type of object which is to be represented by the imported chromatic fields set.
Returns
The imported ChromaticFieldsSet_1D.

◆ ImportTextFileIntoComplexField()

static ? ComplexField ImportTextFileIntoComplexField ( string fileName,
bool expectComplexValues,
int firstRow,
int lastRow,
int numberOfCharactersToSkip,
string commentIndicator,
string columnSeparator,
string decimalSeparator,
string groupSeparator,
out List<(bool is1D, bool? isGridless, bool? isEquidistant, bool? dataInColumns, int noOfSubsets)> possibleCombinations )
static

Imports a text file into a ComplexField object.

Parameters
fileNameFull path of the file to import.
expectComplexValuesIf true, the values in the file are expected to be complex-valued. If the import is successful, the result will be complex-valued as well.
firstRowThe first row to read from file. If set to -1, all lines will be processed.
lastRowThe last row to read from file. If set to -1, all lines will be processed.
numberOfCharactersToSkipIf greater than zero, this number of characters will be ignored at the beginning of each line.
commentIndicatorThe character to be interpreted as comment indicator, preceding lines which are to be ignored.
columnSeparatorCharacter which separates columns in the file. Please note: All 'white-space' characters are interchangeable. This means, for example, providing a blank will work with tabulator-separated columns and vice versa.
decimalSeparatorCharacter which separates the integer part from the fractional part of the numbers in the file.
groupSeparatorCharacter which 'groups' three digits respectively, so it can be called 'thousands separator' as well. This parameter may be left empty, meaning that no group separator is used in the file.
possibleCombinationsList of all possible property combinations a DataArray, constructed from the imported ComplexField, could have.
Returns
The read ComplexField if the import worked well. Otherwise null will be returned.

◆ ImportTextFileIntoDataArray()

static ? DataArrayBase ImportTextFileIntoDataArray ( string fileName,
bool expectComplexValues = false,
bool coordinatesAreCodedInData = false,
double samplingDistanceX = 1,
double samplingDistanceY = 1,
string commentIndicator = "#",
string columnSeparator = " ",
string decimalSeparator = ".",
string groupSeparator = "",
int firstRow = -1,
int lastRow = -1,
int numberOfCharactersToSkip = 0,
bool prefer2Dover1D = true,
bool preferGriddedOverGridless = true,
bool expect1DOrGridlessDataInColumns = true,
bool decreasingXCoordinates = false,
bool decreasingYCoordinates = false,
PhysicalMeaningType typeOfDA = PhysicalMeaningType::None )
static

Imports a text file into a DataArray object.

Parameters
fileNameThe full path of the text file to be imported.
expectComplexValuesAre the data to be interpreted as being complex-valued?
samplingDistanceXIf the coordinates are not coded within the data, this gives the sampling distance to be used in 1D case or the sampling distance for the x-coordinates in 2D case.
samplingDistanceYIf the coordinates are not coded within the data, this gives the sampling distance to be used for the y-coordinates in 2D case.
commentIndicatorThe character to be interpreted as comment indicator, preceding lines which are to be ignored.
columnSeparatorCharacter which separates columns in the file. Please note: All 'white-space' characters are interchangeable. This means, for example, providing a blank will work with tabulator-separated columns and vice versa.
decimalSeparatorCharacter which separates the integer part from the fractional part of the numbers in the file.
groupSeparatorCharacter which 'groups' three digits respectively, so it can be called 'thousands separator' as well. This parameter may be left empty, meaning that no group separator is used in the file.
firstRowThe first row to read from file. If set to -1, all lines will be processed.
lastRowThe last row to read from file. If set to -1, all lines will be processed.
numberOfCharactersToSkipIf greater than zero, this number of characters will be ignored at the beginning of each line.
prefer2Dover1DIf the data can be interpreted as 2D or 1D, which one has to be preferred (2D = true vs. 1D = false)?
preferGriddedOverGridlessIf the data are 2D and can be interpreted as being on a coordinate grid as well as being 'gridless', which one has to be preferred (gridded = true vs. gridless = false)?
coordinatesAreCodedInDataAre the coordinates for all of the data points given in the text data (being the first column and/or row of values) as well?
expect1DOrGridlessDataInColumnsIf the data are 1D or gridless 2D where each of several data sets can be in columns as well as in rows - which option is preferred (column-wise = true vs. row-wise = false)?
decreasingXCoordinatesIf the coordinates are not given in the file, are the actual x-coordinates to be interpreted as decreasing with increasing column- (or row-) index?
decreasingYCoordinatesIf the coordinates are not given in the file, are the actual y-coordinates to be interpreted as decreasing with increasing row-index?
typeOfDAThe type of object which is to be represented by the imported data array.
Returns
The imported DataArray. It has to be casted into DataArray2D, DataArray1D, or DataArrayGridless first before it can be processed further.

◆ ImportTextFileIntoHarmonicField()

static ? ComplexAmplitude ImportTextFileIntoHarmonicField ( string fileName,
double wavelength,
bool expectComplexValues = false,
string commentIndicator = "#",
string columnSeparator = " ",
string decimalSeparator = ".",
string groupSeparator = "",
int firstRow = -1,
int lastRow = -1,
int numberOfCharactersToSkip = 0 )
static

Imports a text file into a HarmonicField object.

Parameters
fileNameFull path of the file to import.
wavelengthWavelength for the new HarmonicField.
expectComplexValuesIf true, the values in the file are expected to be complex-valued. If the import is successful, the result will be complex-valued as well.
firstRowThe first row to read from file. If set to -1, all lines will be processed.
lastRowThe last row to read from file. If set to -1, all lines will be processed.
numberOfCharactersToSkipIf greater than zero, this number of characters will be ignored at the beginning of each line.
commentIndicatorThe character to be interpreted as comment indicator, preceding lines which are to be ignored.
columnSeparatorCharacter which separates columns in the file. Please note: All 'white-space' characters are interchangeable. This means, for example, providing a blank will work with tabulator-separated columns and vice versa.
decimalSeparatorCharacter which separates the integer part from the fractional part of the numbers in the file.
groupSeparatorCharacter which 'groups' three digits respectively, so it can be called 'thousands separator' as well. This parameter may be left empty, meaning that no group separator is used in the file.
Returns
The read ComplexField if the import worked well. Otherwise null will be returned.

◆ LoadField()

static ComplexAmplitude LoadField ( string fileName)
static

Loads a field from a file.

Parameters
fileNameFull path of the file to load. Note that backslashes must be doubled, for example “C:\myField.ca2”.
Returns
The loaded field.

◆ LoadFieldsSet()

static HarmonicFieldsSet LoadFieldsSet ( string fileName)
static

Loads a fields set from a file.

Parameters
fileNameFull path of the file to load. Note that backslashes must be doubled, for example “C:\myFieldsSet.hfs”
Returns
The loaded fields set.

◆ NumberOfLines()

static int NumberOfLines ( string fileName)
static

Returns the number of lines in the text file specified by fileName.

Parameters
fileNameThe full path of the file from which the text is to be read. Note that backslashes must be doubled, for example “C:\log.txt”.
Returns
The number of lines in the specified text file.

◆ ProcessOpticalSetup()

static void ProcessOpticalSetup ( string fileNameOpticalSetup,
string outputFolder,
string fileNameParameters = "",
PropagationEngine? simulationEngine = null,
int? analyzerIndex = null,
bool useSubfolder = false )
static

Loads and simulates the given Optical Setup file.

Parameters
fileNameOpticalSetupThe complete path of the Optical Setup file.
outputFolderThe folder to which all results are written. Note that messages, warnings, and errors are still written to the Messages tab of the main window of VirtualLab Fusion.
fileNameParametersIf you specify this optional parameter, the parameters of the Optical Setup are overwritten with the parameters of that given file. The file must be in a specific XML format which can be generated by exporting an Optical Setup to batch mode files within VirtualLab Fusion.
simulationEngineThe simulation engine to use. If this optional parameter is not specified, the given analyzer is executed instead.
analyzerIndexIndex of the analyzer to be executed. If this optional parameter is not specified and also no simulation engine, then the default simulation engine as defined in the Global Options is used.
useSubfolderIf set to true a unique sub-folder for each simulation run is generated.

◆ ReadLine()

static string ReadLine ( string fileName,
int lineNumber )
static

Returns the nth line of the text file specified by fileName, where \(n\) equals the lineNumber. The first line of the file is line number 1. If the file does not exist or the specified line number is beyond the end of the file, the program using this method will be stopped unless the thrown exception is handled outside of this method.

Parameters
fileNameThe full path of the file from which the text is to be read. Note that backslashes must be doubled, for example “C:\log.txt”.
lineNumberThe line number to be read.
Returns
The read line.
Exceptions
System.ArgumentExceptionLine number must be between 1 and the number of lines in the file.

◆ SaveDocument()

static void SaveDocument ( IDocument document,
string fileName )
static

Saves a document (e. g. a ComplexAmplitude or a HarmonicFieldsSet object) to the hard disc.

Parameters
documentThe document to save.
fileNameThe desired file name including the full path. Note that backslashes must be doubled, for example “C:\myField.ca2”

◆ WriteLineToLogFile()

static void WriteLineToLogFile ( string fileName,
string message )
static

Writes a string as a separate line to the end of the specified log file.

Parameters
fileNameThe full path of the file into which the text is to be written. Note that backslashes must be doubled, for example “C:\log.txt”. If the file does not exist, it is created.
messageThe string to write into the log file.

◆ WriteToLogFile()

static void WriteToLogFile ( string fileName,
string message )
static

Writes a string to the end of the specified log file. In contrast to the WriteLineToLogFile method, this method does not introduce a line break.

Parameters
fileNameThe full path of the file into which the text is to be written. Note that backslashes must be doubled, for example “C:\log.txt”. If the file does not exist, it is created.
messageThe string to write into the log file.