|
Render Toolbox 3
v2.1
|
Miscellaneous utilities. More...
Functions | |
| sortedPath originalPath | DemoteEnvPathEntries (variable, matching) |
| Move some environment path entries to the end of the path. | |
| status result output | RunMitsuba (sceneFile, hints) |
| Invoke the Mitsuba renderer. | |
| status result output | RunPBRT (sceneFile, hints) |
| Invoke the PBRT renderer. | |
| wasCreated | ChangeToFolder (folder) |
| Change to the given folder, create it if necessary. | |
| wasCreated | ChangeToWorkingFolder (hints) |
| Change to the working folder for a recipe, create it if necessary. | |
| CleanMatlabPath () | |
| Remove '.svn' and '.git' folders from the Matlab path. | |
| fileList | FindFiles (folder, filter, isFolders, isExact) |
| Locate files at or below the given folder. | |
| wavelengths magnitudes sRGB | GetPixelSpectrum (image, spectrum, x, y) |
| Get wavelengths and magnitudes from a multi-spectral image pixel. | |
| userFolder | GetUserFolder () |
| Locate the user's "MATLAB" documents folder. | |
| absolutePath | GetWorkingAbsolutePath (originalPath, hints) |
| Convert a relative working path to a local absoute path. | |
| folder | GetWorkingFolder (folderName, isRendererSpecific, hints) |
| Get a complete RenderToolbox3 working folder folder. | |
| relativePath | GetWorkingRelativePath (originalPath, hints) |
| Convert a local absoute path to a relative working path. | |
| outFiles | ImportPsychColorimetricMatFile (inFile, outFile, isDivideBands) |
| Convert a Psychtooblox colorimetric mat-file to text spd-files. | |
| InitializeRenderToolbox (isForce) | |
| Create Matlab preferences for RenderToolbox3. | |
| isPrefix remainder | IsPathPrefix (pathA, pathB) |
| Is the first path a prefix (i.e. | |
| isPresent | IsStructFieldPresent (s, fieldName) |
| Does a struct have a particular field? | |
| isClockwise | IsVerticesClockwise (vertices) |
| Check the winding order of vertices in 3D space. | |
| outFiles | MakeSensorImages (inFiles, matchingFunctions, matchingS, matchingNames, hints) |
| Write sensor image data files based on multi-spectral data files. | |
| sensorImage | MultispectralToSensorImage (multispectralData, imageS, matchingFunction, matchingS) |
| Convert multi-spectral data to a sensor image representation. | |
| sRGBImage XYZImage rawRGBImage | MultispectralToSRGB (multispectralImage, S, toneMapFactor, isScale) |
| Convert multi-spectral image data to XYZ and sRGB. | |
| data S category name | ParsePsychColorimetricMatFile (dataFile) |
| Read data and metadata from a Psychtoolbox colorimetric .mat file. | |
| numbers nNums | ReadStringNumbers (string, nGrouping) |
| Read numbers from a string, with optional grouping. | |
| renderResults comparison | RenderToolbox3InstallationTest (referenceRoot) |
| Make sure a new RenderToolbox3 installation is working. | |
| rootPath | RenderToolboxRoot () |
| Get the path to RenderToolbox3. | |
| fileInfo | ResolveFilePath (fileName, rootFolder) |
| Resolve a path to the given file. | |
| status result exception | RunCommand (command, hints) |
| Run a system command and capture results or display them live. | |
| newLibPath originalLibPath libPathName | SetRenderToolboxLibraryPath () |
| Tell the operating system where to find dynamic libraries for RenderToolbox3. | |
| ShowXYZAndSRGB (XYZImage, SRGBImage, name, hints) | |
| Plot XYZ and sRGB image representations. | |
| nX nY nZ edges | ShowXYZHistogram (XYZImage, nEdges, hints) |
| Plot histograms for XYZ image components. | |
| spdPerWlBand | SpdPowerPerNmToPowerPerWlBand (spdPerNm, S) |
| Convert spectral power-per-nanometer to power-per-wavelength-band. | |
| spdPerNm | SpdPowerPerWlBandToPowerPerNm (spdPerWlBand, S) |
| Convert spectral power-per-wavelength-band to power-per-nanometer. | |
| promoted S RGB dataFile | PromoteRGBReflectance (reflectance, illuminant, hints) |
| Promote an RGB reflectance to a full spectrum, using a renderer. | |
| vector | StringToVector (string) |
| Convert a string representation of numbers to a 1D matrix. | |
| string | VectorToString (vector) |
| Convert a 1D matrix of numbers to string representation. | |
| newFileName | WriteASCII7BitOnly (fileName, newFileName) |
| Remove characters from the given text file that are not 7-bit ASCII. | |
| gammaImage rawImage | XYZToSRGB (XYZImage, toneMapFactor, toneMapMax, isScale) |
| Convert an image in XYZ space to sRGB color space. | |
Miscellaneous utilities.
| sortedPath originalPath DemoteEnvPathEntries | ( | variable | , |
| matching | |||
| ) |
Move some environment path entries to the end of the path.
| variable | name of an environment variable that contains a path |
| matching | regular expression to match path entries |
variable should be the name of an environment variable that contains a path, such as "PATH" or "LD_LIBRARY_PATH". Modifies the value of the named variable so that path entries matching the given matching regular expression appear last. variable is acceessed with Matlab's built-in getenv() function and modified with the built-in setenv() function.
Returns the new value for the named path variable, sorted so that path entires that match the given matching expression appear last. Also returns the original value for the named variable.
Usage: [sortedPath, originalPath] = DemoteEnvPathEntries(variable, matching)
Example usage:
| status result output RunMitsuba | ( | sceneFile | , |
| hints | |||
| ) |
Invoke the Mitsuba renderer.
| sceneFile | filename or path of a Mitsuba-native scene file. |
| hints | struct of RenderToolbox3 options, see GetDefaultHints() |
Invoke the Mitsuba renderer on the given Mitsuba-native sceneFile. This function handles some of the boring details of invoking Mitsuba with Matlab's unix() command.
if hints.isPlot is provided and true, displays an sRGB representation of the output image in a new figure.
Returns the numeric status code and text output from Mitsuba. Also returns the name of the expected output file from Mitsuba. Usage: [status, result, output] = RunMitsuba(sceneFile, hints)
| status result output RunPBRT | ( | sceneFile | , |
| hints | |||
| ) |
Invoke the PBRT renderer.
| sceneFile | filename or path of a PBRT-native text scene file. |
| hints | struct of RenderToolbox3 options, see GetDefaultHints() |
Invoke the PBRT renderer on the given PBRT-native text sceneFile. This function handles some of the boring details of invoking PBRT with Matlab's unix() command.
if hints.isPlot is provided and true, displays an sRGB representation of the output image in a new figure.
RenderToolbox3 assumes that relative paths in scene files are relative to hints.workingFolder. But PBRT assumes that relative paths are relative to the folder that contains the scene file. These are usually different folders. This function copies sceneFile into hints.workingFolder so that relative paths will work using the RenderTooblox3 convention.
Returns the numeric status code and text output from PBRT. Also returns the name of the expected output file from PBRT. Usage: [status, result, output] = RunPBRT(sceneFile, hints)
| wasCreated ChangeToFolder | ( | folder | ) |
Change to the given folder, create it if necessary.
| folder | path where to cd() to |
Just cd() to the folder. Create it if it doesn't exist already.
Returns true if folder had to be created.
Usage: wasCreated = ChangeToFolder(folder)
| wasCreated ChangeToWorkingFolder | ( | hints | ) |
Change to the working folder for a recipe, create it if necessary.
| hints | struct of RenderToolbox3 options, see GetDefaultHints() |
cd() to the working folder for the given hints, used by a recipe. See GetWorkingFolder(). Create the working folder if it doesn't exist yet.
Returns true if folder had to be created.
Usage: wasCreated = ChangeToWorkingFolder(hints)
| CleanMatlabPath | ( | ) |
Remove '.svn' and '.git' folders from the Matlab path.
Modifies the Matlab path, removing path entries that contain '.git' or '.svn'. You should save the path afterwards. You can use this function while the Matlab "Set Path" dialog is open!
Usage: CleanMatlabPath()
| fileList FindFiles | ( | folder | , |
| filter | , | ||
| isFolders | , | ||
| isExact | |||
| ) |
Locate files at or below the given folder.
| folder | path where to start looking for files |
| filter | optional regular expression for filtering files |
| isFolders | whether to search for files as well as folders |
| isExact | whether to use filter for exact file name matching |
FindFiles() recursively searches folder and its subfolders for files. If folder is omitted, uses pwd(). By default, returns all files. filter may contain a regular expression, in which case only files whose names match are included. Matching is performed on full, absolute path names.
By default, only returns file names, not folder names. If isFolders is provided and true, returns folder names as well as file names.
Ignores subfolders that contain '.'. Ignores files that start with '.' or end with "~" or "ASV".
Returns a cell array of string which are the full, absolute path names of files that were found and matched.
Usage: fileList = FindFiles(folder, filter, isFolders, isExact)
| wavelengths magnitudes sRGB GetPixelSpectrum | ( | image | , |
| spectrum | , | ||
| x | , | ||
| y | |||
| ) |
Get wavelengths and magnitudes from a multi-spectral image pixel.
| image | multispectral data matrix of size [height width n] |
| spectrum | description of the n spectrum bands of image |
| x | x-coordinate of the pixel to probe |
| y | y-coordinate of the pixel to probe |
Gets the spectral magnitude distribution of one pixel in the given multi-spectral image.
image must be a multi-spectral image matrix, with size [height width n], where height and width are the image pixel dimensions, and n is the number of spectrum bands in the image.
spectrum must be a description of the n spectrum bands in image. spectrum may be a 1 x n list of wavelengths, or it may be an "S" description of the form [start delta n], where start is the wavelength of the lowest spectrum band, and delta is the width of each band.
x and y must be the x-coordinage and y-coordinate of the pixel of interest.
Returns a 1 x n matrix of n wavelengths, and a corresponding 1 x n matrix of magnitudes, for the pixel of interest. Also returns an sRGB approximation of the spectrum of the pixel of interest.
Usage: [wavelengths, magnitudes, sRGB] = GetPixelSpectrum(image, spectrum, x, y)
| userFolder GetUserFolder | ( | ) |
Locate the user's "MATLAB" documents folder.
Use the built-in userpath() function to return the path to the user's "MATLAB" documents folder. This folder is usually located in a "Documents" folder inside a user's home folder. This is usually a location where Matlab will have permission to write files.
Users can change their path configuration using userpath(). If for some reason userpath() does not return a valid location, returns ''.
Returns the full absolute path to a user's "MATLAB" documents folder, or '' if the documents path could not be found.
Usage: userFolder = GetUserFolder()
| absolutePath GetWorkingAbsolutePath | ( | originalPath | , |
| hints | |||
| ) |
Convert a relative working path to a local absoute path.
| originalPath | string relative working path to convert |
| hints | struct of RenderToolbox3 options, see GetDefaultHints() |
Converts the given originalPath to a local absolute path. Assumes that originalPath is a relative path relative to the working folder specified by the given hints. See GetWorkingFolder().
Usage: absolutePath = GetWorkingAbsolutePath(originalPath, hints)
| folder GetWorkingFolder | ( | folderName | , |
| isRendererSpecific | , | ||
| hints | |||
| ) |
Get a complete RenderToolbox3 working folder folder.
| folderName | string name of a RenderToolbox3 recipe folder |
| isRendererSpecific | whether or not folder is renderer specific |
| hints | struct of RenderToolbox3 options, see GetDefaultHints() |
Returns the full path to a RenderToolbox3 recipe folder. This will include the given .workingFolder and .recipeName, plus an optional folderName name like "resources" or "renderings". If isRendererSpecific is true, also includes a subfolder named for the given hints.renderer.
If the returned folder does not exist yet, creates it.
folderName may be one of the folowing:
If hints is not provided, uses GetDefaultHints() instead.
Usage: folder = GetWorkingFolder(folderName, isRendererSpecific, hints)
| relativePath GetWorkingRelativePath | ( | originalPath | , |
| hints | |||
| ) |
Convert a local absoute path to a relative working path.
| originalPath | string file name or absolute path to convert |
| hints | struct of RenderToolbox3 options, see GetDefaultHints() |
Converts the given originalPath to a relative path, relative to the working folder specified by the given hints. See GetWorkingFolder().
If originalPath can be found within the working folder specified by the given hints, returns the corresponding relative path, starting from the working folder. Otherwise, returns ''.
Usage: relativePath = GetWorkingRelativePath(originalPath, hints)
| outFiles ImportPsychColorimetricMatFile | ( | inFile | , |
| outFile | , | ||
| isDivideBands | |||
| ) |
Convert a Psychtooblox colorimetric mat-file to text spd-files.
| inFile | input .mat file with Psychtooblox colorimetric data |
| outFile | output file name for new text file(s) |
| isDivideBands | whether to divide spectrum samples by band width |
Converts the Psychtoolbox colorimetric mat-file inFile to one or more text spd-files named outFile. Text spd-files are suitable for use with PBRT and Mitsuba.
inFile should be the name of a mat-file which obeys Psychtoolbox colorimetric mat file conventions. The name should use a descriptive prefix, followed by an underscore, followed by a specific name. For example, RenderToolbox includes "sur_mccBabel.mat":
For more about Psychtooblox colorimetric mat-files and conventions, see the Psychtoolbox web documentation or the file Psychtoolbox/PsychColorimetricData/PsychColorimetricMatFiles/Contents.m
If inFile contains measurements for just one object, the new text file will have the given name outFile. If inFile contains measurements for multiple objects, a separate text file will be written for each object, using the base name of outFile, plus a numeric suffix. For example, "sur_mccBabel.mat" might produce a file named "mccBabel-24.spd".
By convention, all Psychtoolbox colorimetric .mat files describe power spectra as power-per-wavelength-band. This differs from text .spd files, which should describe power spectra as power-per-nanometer. If inFile obeys Psychtoolbox conventions for spectral power .mat files, spectrum samples will be divided by the spectral band width to put them in units of power-per-nanometer. Psychtoolbox conventions for power spectra include using prefix "spd", and storing data with one column per object.
If isDivideBands is provided and true, spectrum samples will be divided by band width, regardless of Psychtoolbox conventions. If isDivideBands is false, spectrum samples will be left unchanged, regardless of Psychtooblox conventions. If isDivideBands is omitted, attempts to follow Psychtoolbox conventions.
Returns a cell array of file names for new text spd-files.
Usage: outFiles = ImportPsychColorimetricMatFile(inFile, outFile, isDivideBands)
| InitializeRenderToolbox | ( | isForce | ) |
Create Matlab preferences for RenderToolbox3.
| isForce | whether to create preferences from scratch (optional) |
Chooses paths and other constants for RenderToolbox3, and makes these available with Matlab's setpref() and getpref() functions.
See RenderToolbox3ConfigurationTemplate.m for examples of how to set up custom RenderToolbox3 preferences.
To see all the RenderToolbox3 default preferences, try:
You can also set the folder where RenderToolbox3 will look for files and write new files.
You can also set other defaults that RenderToolbox3 will use when no "hints" are provided. For example,
Setting these values with setpref() makes the changes persistent. Normally you can set the same values in a temporary way, using a "hints" struct. See GetDefaultHints().
By default, leaves any existing preferences in place. If isForce is provided and true, replaces existing preferences with default values.
| isPrefix remainder IsPathPrefix | ( | pathA | , |
| pathB | |||
| ) |
Is the first path a prefix (i.e.
parent) of the second?
| pathA | string path for a file or folder that exists |
| pathB | string path for another file or folder that exists |
Checks whether the given pathA is a parent of pathB, or if pathA and pathB are equivalent. If so, pathA can be treated as a prefix of pathB.
Only compares leading folder paths, and not file names. For example, in both of the following eamples, pathA is considered a prefix of pathB.
If pathA can be considered a prefix of pathB, returns true. Otherwise returns false. Also returns the remainder of pathB that follows pathA, if any. For example,
Usage: [isPrefix, remainder] = IsPathPrefix(pathA, pathB)
| isPresent IsStructFieldPresent | ( | s | , |
| fieldName | |||
| ) |
Does a struct have a particular field?
| s | a struct |
| fieldName | string field name |
Returns true if the given s has a field with the given fieldName, and if the field is not empty. Otherwise returns false.
Usage: isPresent = IsStructFieldPresent(s, fieldName)
| isClockwise IsVerticesClockwise | ( | vertices | ) |
Check the winding order of vertices in 3D space.
| vertices | m x 3 matrix of XYZ triples |
Returns true if the given vertices are wound in clockwise order. For porposes of this function, "clockwise" is defined arbitrarily and it's only meaningful to compare sets of vertices for differences in winding order.
vertices should contain at least 3 XYZ triples. Only the first 3 will be checked for winding order. Subtracts the first vertex from each of the next two vertices, and takes the cross product of the differences. If the product has a non-negative z-component, vertices are "clockwise". Otherwise they're "counter-clockwise".
Returns true if vertices are wound in clockwise order.
Usage: isClockwise = IsVerticesClockwise(vertices)
| outFiles MakeSensorImages | ( | inFiles | , |
| matchingFunctions | , | ||
| matchingS | , | ||
| matchingNames | , | ||
| hints | |||
| ) |
Write sensor image data files based on multi-spectral data files.
| inFiles | cell array of multi-spectral data file names |
| matchingFunctions | color matching funciton matrices or filenames |
| matchingS | matching function spectral sampling descriptions |
| matchingNames | cell array of matching function names |
| hints | struct of RenderToolbox3 options, see GetDefaultHints() |
Writes new data mat-files that contain sensor images, one for each of the multi-spectral data files given in inFiles. inFiles should be a cell array of multi-spectral .mat data files, as produced by BatchRender().
matchingFunctions and matchingS specify the color matching functions used to convert multi-spectral data to sensor imgaes. matchingFunctions should be a cell array, where each element specifies a separate color matching function. Each element may have one of two forms: it may be a numeric matrix containing color mathing data, or it may be the string name of a Psychtoolbox colorimetric data file.
matchingS is only required if matchingFunctions contains numeric matrices. In that case, each element matchingS corresponds to an element of matchingFunctions, and must contain a description of the matching function's spectral sampling.
See MultispectralToSensorImage() for more about matching functions and spectral sampling descriptions. Elements of matchingFunctions are passed to MultispectralToSensorImage() as the "matchingFunction" argument. Corresponding elements of matchingS are passed as the "matchingS" argument.
matchingNames is optional. If provided, each element of matchingNames corresponds to an element of matchingFunctions, and may contain a descriptive name for that matching function.
hints may be a struct with RenderToolbox3 options. hints.outputDataFolder specifies where sensor image .mat data files will be written.
Returns a cell array of sensor image data file names. Rows of the cell array will correspond to elements of inFiles. Columns of the cell array will corrrespond to elements of matchingFunctions. Each data file name will start with the corresponding inFiles name and end with a descriptive suffix. The suffix will be chosen from available sources, in order of preference:
Usage: outFiles = MakeSensorImages(inFiles, matchingFunctions, matchingS, matchingNames, hints)
| sensorImage MultispectralToSensorImage | ( | multispectralData | , |
| imageS | , | ||
| matchingFunction | , | ||
| matchingS | |||
| ) |
Convert multi-spectral data to a sensor image representation.
| multispectralData | multispectral image matrix |
| imageS | image spectral sampling description |
| matchingFunction | color matching funciton matrix or filename |
| matchingS | matching function spectral sampling description |
Convert the given multispectralData to a sensor image representation, based on the given matchingFunction. multispectralData should have size [height width nImageSpecralSamples] and spectral sampling described by imageS of the form [start delta nImageSpecralSamples]. multispectralData should contain data in units of Power per Unit Wavelength.
matchingFunction may have one of two forms. It may be a matrix with size [nChannels, nMatchingSpecralSamples]. When matchingFunction is a matrix, matchingS must be provided as a description of the matching function spectral sampling, in the form [start delta nMatchingSpecralSamples].
matchingFunction may also be the name of a Psychtoolbox colorimetric data file that contains a matrix of matching function data and an "S" descripton of the matching function spectral sampling. By convention, these data files are named with the prefix "T_". When matchingFunction is a file name, matchingS is ignored.
For more about Psychtooblox colorimetric .mat files and conventions, see the Psychtoolbox web documentation or the file Psychtoolbox/PsychColorimetricData/PsychColorimetricMatFiles/Contents.m
Returns a sensor image representation of the given multispectralData, with size [height width nMatchingSpecralSamples].
Usage: sensorImage = MultispectralToSensorImage(multispectralData, imageS, matchingFunction, matchingS)
| sRGBImage XYZImage rawRGBImage MultispectralToSRGB | ( | multispectralImage | , |
| S | , | ||
| toneMapFactor | , | ||
| isScale | |||
| ) |
Convert multi-spectral image data to XYZ and sRGB.
| multispectralImage | multispectral image matrix [height width n] |
| S | image spectral sampling description [start delta n] |
| toneMapFactor | optional threshold for clipping luminance |
| isScale | whether to normalize sRGB image by max luminance |
Convert the given multispectralImage of size [height width n] to an sRGB image of size [height width 3], for viewing on a standard monitor, using the CIE 1931 standard weighting functions.
The given S must describe the n spectral planes of the multispectralImage. It should have the form [start delta n], where start and delta are wavelengths in nanometers, and n is the number of spectral planes.
If S toneMapFactor is provided and greater than 0, truncates luminances above this factor times the mean luminance.
If isScale is true, the gamma-corrected image will be scaled to use they gamma-corrected maximum.
Returns a gamma-corrected sRGB image of size [height width 3]. Also returns the intermediate XYZ image and the uncorrected RGB image, which have the same size.
Usage: [sRGBImage, XYZImage, rawRGBImage] = MultispectralToSRGB(multispectralImage, S, toneMapFactor, isScale)
| data S category name ParsePsychColorimetricMatFile | ( | dataFile | ) |
Read data and metadata from a Psychtoolbox colorimetric .mat file.
| dataFile | name of a Psychtoolbox colorimetric .mat file. |
Reads the colorimetric data and associated spectral sampling from the given dataFile, which should be a Psychtoolbox colorimetric .mat file. Also parses the name of dataFile according to Pyschtoolox conventions.
For more about Psychtooblox colorimetric .mat files and conventions, see the Psychtoolbox web documentation or the file Psychtoolbox/PsychColorimetricData/PsychColorimetricMatFiles/Contents.m
Returns colorimetric data matrix from the given dataFile, the "S" description of the data's spectral sampling, the category prefix from the file name, and the descriptive base file name.
Usage: [data, S, prefix, name] = ParsePsychColorimetricMatFile(dataFile)
| numbers nNums ReadStringNumbers | ( | string | , |
| nGrouping | |||
| ) |
Read numbers from a string, with optional grouping.
| string | a string to scan for numbers |
| nGrouping | how many numbers to include in each group (optional) |
Reads decimal number representations from the given string. Returns numbers as separate elements of a cell array of strings. By default, each element of the cell array of strings will contain one number. If nGrouping is provided, each element will contain nGrouping numbers. Also returns the total count of numbers found in in the given string.
Usage: [numbers, nNums] = ReadStringNumbers(string, nGrouping)
| renderResults comparison RenderToolbox3InstallationTest | ( | referenceRoot | ) |
Make sure a new RenderToolbox3 installation is working.
| referenceRoot | path to RenderTooblox3 reference data |
Initialize RenderToolbox3 after installation and then put it through some basic tests. If this function runs properly, you're off to the races.
If referenceRoot is provided, it must be the path to a set of RenderToolbox3 reference data. Rendering produced locally will be compared to renderings in the reference data set.
Returns a struct of results from rendering test scenes. If referenceRoot is provided, also returns a struct of comparisons between local renderings and reference renderings.
Usage: [renderResults, comparison] = RenderToolbox3InstallationTest(referenceRoot)
| rootPath RenderToolboxRoot | ( | ) |
Get the path to RenderToolbox3.
Returns the absolute path to RenderToolbox3, based on the location of this file, RenderToolboxRoot.m.
Usage: rootPath = RenderToolboxRoot()
| fileInfo ResolveFilePath | ( | fileName | , |
| rootFolder | |||
| ) |
Resolve a path to the given file.
| fileName | name or path to a file that exists |
| rootFolder | path to a folder that might contain fileName |
Searches for the given fileName, which might be a plain file name, or a relative or absolute path to a file. First searches within rootFolder and its subfolders for a file that matches fileName. If no match is found within rootFolder, searches for a matching file on the Matlab path.
If rootFolder is omitted, searches with the current folder and its subfolders instead.
Returns a struct of info about the given fileName, with the following fields:
resolvedPath will be an unambiguous path to the first file that matches fileName. If the match was found within rootFolder, resolvedPath is the relative path to the matched file, starting from rootFolder. If the match was found on the Matlab path, but not in rootFolder, resolvedPath is the full absolute path to the matched file. If no match was found, resolvedPath is the empty string ''.
In all cases, isRootFolderMatch indicates whether or not a match was found within rootFolder. When isRootFolderMatch is true, resolvedPath should be treated as a relative path.
Usage: fileInfo = ResolveFilePath(fileName, rootFolder)
|
final |
Run a system command and capture results or display them live.
| command | string command to run with built-in system() |
| hints | struct of RenderToolbox3 options, see GetDefaultHints() |
RunCommand() executes the given command string using Matlab's built-in system() function, and attempts to capture status codes and messages that result. Attempts to never throw an exception. Instead, captures and returns any exception thrown.
If hints.isCaptureCommandResults is false, allows Matlab to print command results to the Command Window immediately as they happen, instead of capturing them. If is omitted, uses GetDefaultHints().
Returns the numeric status code and string result from the system() function. The result may be empty, if hints.isCaptureCommandResults is false. Also returns any exception that was thrown during command execution, or empty [] if no exception was thrown.
Usage: [status, result, exception] = RunCommand(command, hints)
| newLibPath originalLibPath libPathName SetRenderToolboxLibraryPath | ( | ) |
Tell the operating system where to find dynamic libraries for RenderToolbox3.
Configures the operating system environment to locate dynamic libraries that are required for RenderToolbox3. The correct dynamic library configuration is highly platform-specific. On some machines setting up the library path is trivial, on others it is a pain in the neck.
This function is invoked automatically by RenderToolbox3 utilities. Most users should not need to invoke this function.
Uses configuration values stored with Matlab's built-in getpref() and setpref() functions. Reasonable default values are chosen in InitializeRenderToolbox(). Most users will not need to change these. If you know what you're doing, you can customize these values using setpref():
Modifies the system's dynamic library search path, using the values stored in getpref('RenderToolbox3', 'libPathName'), getpref('RenderToolbox3', 'libPath'), and getpref('RenderToolbox3', 'libPathLast').
Returns the new value of the system dynamic library search path. Also returns the original path value. Also returns the name of the dynamic library search path environment variable.
Usage: [newLibPath, originalLibPath, libPathName] = SetRenderToolboxLibraryPath()
Example usage:
| ShowXYZAndSRGB | ( | XYZImage | , |
| SRGBImage | , | ||
| name | , | ||
| hints | |||
| ) |
Plot XYZ and sRGB image representations.
| XYZImage | image matrix with XYZ color data |
| SRGBImage | image matrix with sRGB color data |
| name | a name to give the images (optional) |
| hints | struct of RenderToolbox3 options, see GetDefaultHints() |
Quick plotter for XYZ and sRGB image representations. The given XYZImage and SRGB image will be plotted in new figures. If name is provided, it will appear as the image title.
If hints is provided, it must be a struct of RenderToolbox3 options, as returned from GetDefaultHints(). If hints.isPlot is false, returns without plotting anything.
| nX nY nZ edges ShowXYZHistogram | ( | XYZImage | , |
| nEdges | , | ||
| hints | |||
| ) |
Plot histograms for XYZ image components.
| XYZImage | matrix of XYZ image data |
| nEdges | how many bin edges to use in histograms |
| hints | struct of RenderToolbox3 options, see GetDefaultHints() |
Plots histograms of X, Y, and Z components of the given XYZimage, in a new figure. XYZimage should be in Psychtoolbox "Image" format (as opposed to "Calibration" format), with size [nY, nX, 3].
By default, plots histograms with 100 bin edges. If nEdges is provided, uses the given number of bin edges. All components will share the same bin edges, ranging from a common minimum to a commpn maximum. 0-values are ignored.
Returns the bin frequency counts for each component, X, Y, and Z. Also returns the array of bin edges.
If hints is provided, it must be a struct of RenderToolbox3 options, as returned from GetDefaultHints(). If hints.isPlot is false, returns without plotting anything.
Usage: [nX, nY, nZ, edges] = ShowXYZHistogram(XYZImage, nEdges, hints)
| spdPerWlBand SpdPowerPerNmToPowerPerWlBand | ( | spdPerNm | , |
| S | |||
| ) |
Convert spectral power-per-nanometer to power-per-wavelength-band.
| spdPerNm | matrix of data with power-per-nanometer |
| S | description of wavelength sampling, [start delta n] |
Converts the given spdPerNm matrix, which should contain a spectral power distribution with samples in units of power-per-nanometer, to the equivalent distribution with in units of power-per-wavelength-band. The given S must describe the spectral sampling used in spdPerNm, and determines the correct conversion factor.
Returns the given spdPerNm, multiplied with the spectral sampling band width in the given S.
Usage: spdPerWlBand = SpdPowerPerNmToPowerPerWlBand(spdPerNm, S)
| spdPerNm SpdPowerPerWlBandToPowerPerNm | ( | spdPerWlBand | , |
| S | |||
| ) |
Convert spectral power-per-wavelength-band to power-per-nanometer.
| spdPerWlBand | matrix of data with power-per-wavelength-band |
| S | description of wavelength sampling, [start delta n] |
Converts the given spdPerWlBand matrix, which should contain a spectral power distribution with samples in units of power-per-wavelength-band, to the equivalent distribution with in units of power-per-nanometer. The given S must describe the spectral sampling used in spdPerWlBand, and determines the correct conversion factor.
Returns the given spdPerWlBand, divided by the spectral sampling band width in the given S.
Usage: spdPerNm = SpdPowerPerWlBandToPowerPerNm(spdPerWlBand, S)
| promoted S RGB dataFile PromoteRGBReflectance | ( | reflectance | , |
| illuminant | , | ||
| hints | |||
| ) |
Promote an RGB reflectance to a full spectrum, using a renderer.
| reflectance | RGB reflectance to promote to spectrum |
| illuminant | illuminant spectrum to use in rendering |
| hints | struct of RenderToolbox3 options, see GetDefaultHints() |
Converts the given RGB reflectance to a full multi-spectral representation, by rendering a simple scene that contains a matte reflector with the given RGB surface reflectance, illuminated by a directional "sun" light with the given illuminant spectrum.
reflectance should have RGB components in the range [0 1].
The renderer will "promote" the given RGB reflectance to its own internal spectral representation, perform rendering, and output some pixels that have spectral values that depend a few factors:
This function estimates the "promoted" reflectance spectrum that the renderer used internally:
The obtained "promoted" spectrum will expose the "shape" of the renderer's sprctral promotion algorithm, but not scaling effects.
This function also down-converts the "promoted" spectrum to down to an RGB representation, for direct comparison with the given reflectance. The down-conversion uses the CIE XYZ 1931 color matching functions. The down-converted RGB reflectance will not necessarily match the original reflectance, but might nevertheless be of interest.
By default, uses a "white" illuminant spectrum with unit untensity at all wavelengths. If illuminant is provided, it must be a formatted string or name of a formatted text file that contains spectrum data. See ReadSpectrum() for string and text file formats.
hints may be a struct with options that affect the rendering process, as returned from GetDefaultHints(). If hints is omitted, default options are used. hints.renderer specifies which renderer to use.
Returns the estimated, "promoted" reflectance spectrum that the renderer used internally. Also returns the "S" description of the renderer's wavelength sampling. Also returns the down-converted RGB representation of the promoted spectrum. Finally, returns the name of the .mat file that contains renderer ouput data and metadata from the simple scene rendering.
Usage: [promoted, S, RGB, dataFile] = PromoteRGBReflectance(reflectance, illuminant, hints)
| vector StringToVector | ( | string | ) |
Convert a string representation of numbers to a 1D matrix.
| string | a string with numeric representations |
Scans the given string for integer or decimal numeric representations, and converts them to numeric form.
Returns a 1-dimensional double matrix containing the numbers represented in . If string is not a string, returns the string as it is.
Usage: vector = StringToVector(string)
| string VectorToString | ( | vector | ) |
Convert a 1D matrix of numbers to string representation.
| vector | numeric 1-dimensional matrix |
Prints the given vector to a string with space-separated decimal representations. If all elements of the vector are integers, prints integer representations. Treats vector as 1-dimensional.
Returns a string that contains representations of all the elements of vector. If vector is not numeric, returns the vector as it is.
Usage: string = VectorToString(vector)
| newFileName WriteASCII7BitOnly | ( | fileName | , |
| newFileName | |||
| ) |
Remove characters from the given text file that are not 7-bit ASCII.
| fileName | file name of path of an existing text file |
| newFileName | file name of path for a new text file |
Reads the text file at the given fileName, and writes a new file at the given newFileName that contains only 7-bit ASCII characters. These characters include the usual alphanumerics and some punctuation. Try:
Returns the name of the new file.
Usage: newFileName = WriteASCII7BitOnly(fileName, newFileName)
| gammaImage rawImage XYZToSRGB | ( | XYZImage | , |
| toneMapFactor | , | ||
| toneMapMax | , | ||
| isScale | |||
| ) |
Convert an image in XYZ space to sRGB color space.
| XYZImage | matrix of XYZ image data |
| toneMapFactor | relative luminance truncation (optional) |
| toneMapMax | absolute luminance truncation (optional) |
| isScale | whether or not to scale in gamma correction (optional) |
Converts an image in XYZ colors to sRGB colors, using a few Psychtoolbox functions. The given XYZ image should be a matrix of size [height width n] with XYZ color data. If toneMapFactor is greater than 0, truncates luminance above this factor times the mean luminance. If toneMapMax is greater than 0, truncates luminance above this fixed value. If isScale is true, the gamma-corrected image will be scaled to use the gamma-corrected maximum. Returns a matrix of size [height width n] with gamma corrected sRGB color data. Also returns a matrix of the same size with uncorrected sRGB color data.
Usage: [gammaImage, rawImage] = XYZToSRGB(XYZImage, toneMapFactor, toneMapMax, isScale)
1.8.2
