Class VL_Files

Namespace

VirtualLab.Programming

Assembly

VirtualLab.Programming.dll

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.

public static class VL_Files

Inheritance

object

VL_Files

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Methods

CalculateBitmapFromChromaticFieldsSet2D(ChromaticFieldsSet, double, out bool, bool, Size?, PhysicalValueRange?, PhysicalValueRange?)

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

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

Parameters

cfs ChromaticFieldsSet

Chromatic fields set to create the bitmap from

brightnessFactor double

Factor to increase or decrease the brightness in the bitmap to be calculated. Too high brightness can lead to oversaturation.

noVisibleWavelength bool

Out parameter that indicates whether none of the wavelengths is in the range of visible wavelengths.

interpolated bool

If 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.

numberOfPixels Size?

Number of pixels in the resulting bitmap. If this optional parameter is not specified, one pixel per sampling point is created.

xRange PhysicalValueRange

Optional 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.

yRange PhysicalValueRange

Optional 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

Bitmap

The bitmap created from the Chromatic Fields Set.

CalculateBitmapFromDataArray2D(DataArray2D, int, FieldQuantity, bool, Size?, PhysicalValueRange?, PhysicalValueRange?, double, double, ColorLookUpTableForDataView2D?, Color?, double, bool)

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

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

Parameters

dataArray DataArray2D

Data Array to create the bitmap from

subsetIndex int

The index of that data subset of the Data Array to be converted to the bitmap.

fieldQuantity FieldQuantity

The field quantity to be converted to the bitmap.

interpolated bool

If 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.

numberOfPixels Size?

Number of pixels in the resulting bitmap. If this optional parameter is not specified, one pixel per sampling point is created.

xRange PhysicalValueRange

Optional 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.

yRange PhysicalValueRange

Optional 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.

minValue double

Optional minimum value to be mapped to a color. All values below will have the same color as this value.

maxValue double

Optional maximum value to be mapped to a color. All values above will have the same color as this value.

colorTable ColorLookUpTableForDataView2D

Optional color table for mapping double values to colors. By default the corresponding Global Option is used.

colorForUndefined Color?

Color to be used for undefined values. By default the corresponding Global Option is used.

relativeThresholdForPhaseArtifacts double

Threshold for suppressing phase artifacts. If set to zero or below, no suppression will be done. In case this flag is set to true, the expensive SincFFT will be replaced by TruncatedSinc. Applies only if parameter fieldQuantity is set to FieldQuantity.Phase.

replaceSincFFTbyTruncatedSinc bool

Returns

Bitmap

The bitmap created from the DataArray2D

ImportBitmap(string)

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.

public static IDocument? ImportBitmap(string fileName)

Parameters

fileName string

Full path of image to be imported.

Returns

IDocument

Either a HarmonicFieldsSet (for RGB image) or a DataArray (for indexed or gray-scale image).

ImportGrayScaleBitmap(string, double, double, FieldQuantity, PrecisionMode, double?)

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.

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

Parameters

fileName string

File name of the bitmap to be imported.

minimumValue double

Optional minimum value, i.e. the value of black pixels. 0 by default.

maximumValue double

Optional maximum value, i.e. the value of white pixels. 1 by default.

fieldQuantity FieldQuantity

Optional 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.

precision PrecisionMode

Optional precision. No longer used.

wavelength double?

Optional wavelength. If you specify this value, a Harmonic Field instead of a Jones Matrix Transmission is generated.

Returns

ComplexAmplitude

A ComplexAmplitude with the imported data.

ImportTextFileIntoChromaticFieldsSet(string, double, ChromaticFieldsSetType, double, double, string, string, string, string, int, int, int, bool, bool)

Imports a text file into a ChromaticFieldsSet object.

public 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)

Parameters

fileName string

The full path of the text file to be imported.

wavelength double

The wavelength of the chromatic fields set to be created.

type ChromaticFieldsSetType

The type of object which is to be represented by the imported chromatic fields set.

samplingDistanceX double

The sampling distance to be used for the x-coordinates if the coordinates are not coded within the data.

samplingDistanceY double

The sampling distance to be used for the y-coordinates if the coordinates are not coded within the data.

commentIndicator string

The character to be interpreted as comment indicator, preceding lines which are to be ignored.

columnSeparator string

Character 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.

decimalSeparator string

Character which separates the integer part from the fractional part of the numbers in the file.

groupSeparator string

Character 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.

firstRow int

The first row to read from file. If set to -1, all lines will be processed.

lastRow int

The last row to read from file. If set to -1, all lines will be processed.

numberOfCharactersToSkip int

If greater than zero, this number of characters will be ignored at the beginning of each line.

decreasingXCoordinates bool

Are the actual x-coordinates to be interpreted as decreasing with increasing column-index?

decreasingYCoordinates bool

Are the actual y-coordinates to be interpreted as decreasing with increasing row-index?

Returns

ChromaticFieldsSet

The imported ChromaticFieldsSet.

ImportTextFileIntoChromaticFieldsSet1D(string, List<double>, ChromaticFieldsSetType, bool, double, string, string, string, string, int, int, int, bool, bool)

Imports a text file into a ChromaticFieldsSet_1D object.

public 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)

Parameters

fileName string

The full path of the text file to be imported.

wavelengths List<double>

The wavelengths of the chromatic fields set to be created.

type ChromaticFieldsSetType

The type of object which is to be represented by the imported chromatic fields set.

coordinatesAreCodedInData bool

Are the coordinates for all of the data points given in the text data (being the first column or row of values) as well?

samplingDistance double

The sampling distance to be used if the coordinates are not coded within the data.

commentIndicator string

The character to be interpreted as comment indicator, preceding lines which are to be ignored.

columnSeparator string

Character 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.

decimalSeparator string

Character which separates the integer part from the fractional part of the numbers in the file.

groupSeparator string

Character 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.

firstRow int

The first row to read from file. If set to -1, all lines will be processed.

lastRow int

The last row to read from file. If set to -1, all lines will be processed.

numberOfCharactersToSkip int

If greater than zero, this number of characters will be ignored at the beginning of each line.

expectDataInColumns bool

Several data sets (corresponding to different wavelengths) can be in columns or in rows. Which option is preferred (column-wise = true vs. row-wise = false)?

decreasingCoordinates bool

Are the actual coordinates to be interpreted as decreasing with increasing column- (or row-) index?

Returns

ChromaticFieldsSet_1D

The imported ChromaticFieldsSet_1D.

ImportTextFileIntoComplexField(string, bool, int, int, int, string, string, string, string, out List<(bool is1D, bool? isGridless, bool? isEquidistant, bool? dataInColumns, int noOfSubsets)>)

Imports a text file into a ComplexField object.

public 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)

Parameters

fileName string

Full path of the file to import.

expectComplexValues bool

If 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.

firstRow int

The first row to read from file. If set to -1, all lines will be processed.

lastRow int

The last row to read from file. If set to -1, all lines will be processed.

numberOfCharactersToSkip int

If greater than zero, this number of characters will be ignored at the beginning of each line.

commentIndicator string

The character to be interpreted as comment indicator, preceding lines which are to be ignored.

columnSeparator string

Character 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.

decimalSeparator string

Character which separates the integer part from the fractional part of the numbers in the file.

groupSeparator string

Character 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.

possibleCombinations List<(bool is1D, bool? isGridless, bool? isEquidistant, bool? dataInColumns, int noOfSubsets)>

List of all possible property combinations a DataArray, constructed from the imported ComplexField, could have.

Returns

ComplexField

The read ComplexField if the import worked well. Otherwise null will be returned.

ImportTextFileIntoDataArray(string, bool, bool, double, double, string, string, string, string, int, int, int, bool, bool, bool, bool, bool, PhysicalMeaningType)

Imports a text file into a DataArray object.

public 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)

Parameters

fileName string

The full path of the text file to be imported.

expectComplexValues bool

Are the data to be interpreted as being complex-valued?

coordinatesAreCodedInData bool

Are the coordinates for all of the data points given in the text data (being the first column and/or row of values) as well?

samplingDistanceX double

If 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.

samplingDistanceY double

If the coordinates are not coded within the data, this gives the sampling distance to be used for the y-coordinates in 2D case.

commentIndicator string

The character to be interpreted as comment indicator, preceding lines which are to be ignored.

columnSeparator string

Character 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.

decimalSeparator string

Character which separates the integer part from the fractional part of the numbers in the file.

groupSeparator string

Character 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.

firstRow int

The first row to read from file. If set to -1, all lines will be processed.

lastRow int

The last row to read from file. If set to -1, all lines will be processed.

numberOfCharactersToSkip int

If greater than zero, this number of characters will be ignored at the beginning of each line.

prefer2Dover1D bool

If the data can be interpreted as 2D or 1D, which one has to be preferred (2D = true vs. 1D = false)?

preferGriddedOverGridless bool

If 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)?

expect1DOrGridlessDataInColumns bool

If 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)?

decreasingXCoordinates bool

If the coordinates are not given in the file, are the actual x-coordinates to be interpreted as decreasing with increasing column- (or row-) index?

decreasingYCoordinates bool

If the coordinates are not given in the file, are the actual y-coordinates to be interpreted as decreasing with increasing row-index?

typeOfDA PhysicalMeaningType

The type of object which is to be represented by the imported data array.

Returns

DataArrayBase

The imported DataArray. It has to be casted into DataArray2D, DataArray1D, or DataArrayGridless first before it can be processed further.

ImportTextFileIntoHarmonicField(string, double, bool, string, string, string, string, int, int, int)

Imports a text file into a HarmonicField object.

public 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)

Parameters

fileName string

Full path of the file to import.

wavelength double

Wavelength for the new HarmonicField.

expectComplexValues bool

If 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.

commentIndicator string

The character to be interpreted as comment indicator, preceding lines which are to be ignored.

columnSeparator string

Character 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.

decimalSeparator string

Character which separates the integer part from the fractional part of the numbers in the file.

groupSeparator string

Character 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.

firstRow int

The first row to read from file. If set to -1, all lines will be processed.

lastRow int

The last row to read from file. If set to -1, all lines will be processed.

numberOfCharactersToSkip int

If greater than zero, this number of characters will be ignored at the beginning of each line.

Returns

ComplexAmplitude

The read ComplexField if the import worked well. Otherwise null will be returned.

LoadField(string)

Loads a field from a file.

public static ComplexAmplitude LoadField(string fileName)

Parameters

fileName string

Full path of the file to load. Note that backslashes must be doubled, for example “C:\myField.ca2”.

Returns

ComplexAmplitude

The loaded field.

LoadFieldsSet(string)

Loads a fields set from a file.

public static HarmonicFieldsSet LoadFieldsSet(string fileName)

Parameters

fileName string

Full path of the file to load. Note that backslashes must be doubled, for example “C:\myFieldsSet.hfs”

Returns

HarmonicFieldsSet

The loaded fields set.

NumberOfLines(string)

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

public static int NumberOfLines(string fileName)

Parameters

fileName string

The 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

int

The number of lines in the specified text file.

ProcessOpticalSetup(string, string, string, PropagationEngine?, int?, bool)

Loads and simulates the given Optical Setup file.

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

Parameters

fileNameOpticalSetup string

The complete path of the Optical Setup file.

outputFolder string

The 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.

fileNameParameters string

If 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.

simulationEngine PropagationEngine?

The simulation engine to use. If this optional parameter is not specified, the given analyzer is executed instead.

analyzerIndex int?

Index 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.

useSubfolder bool

If set to true a unique sub-folder for each simulation run is generated.

ReadLine(string, int)

Returns the n^th 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.

public static string ReadLine(string fileName, int lineNumber)

Parameters

fileName string

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

lineNumber int

The line number to be read.

Returns

string

The read line.

Exceptions

ArgumentException

Line number must be between 1 and the number of lines in the file.

SaveDocument(IDocument, string)

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

public static void SaveDocument(IDocument document, string fileName)

Parameters

document IDocument

The document to save.

fileName string

The desired file name including the full path. Note that backslashes must be doubled, for example “C:\myField.ca2”

WriteLineToLogFile(string, string)

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

public static void WriteLineToLogFile(string fileName, string message)

Parameters

fileName string

The 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.

message string

The string to write into the log file.

WriteToLogFile(string, string)

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.

public static void WriteToLogFile(string fileName, string message)

Parameters

fileName string

The 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.

message string

The string to write into the log file.