CmaxwellMxi

Class to manage Maxwell Image files (MXIs).

Enumerations

LightType.

Methods

Static methods

LightType

setMxi

Initializes the CmaxwellMxi object from a Cmxi (Maxwell Core).

getVersion

Gets MXI version supported by the SDK.

getFileVersion

Gets MXI version of the file.

Return value

C++

Cerror::failed() = true: error getting file version.

Cerror::failed() = false: success.

Python

MXI file version.

getScenePath

Returns the path to the MXS file used to render this MXI if it exists.

setScenePath

Sets the path to the MXS file used to render this MXI.

getPreview

Gets the scene preview image. Used to store a thumbnail inside the mxi file. The returned preview is deleted in CmaxwellMxi::~CmaxwellMxi, so the user does not have to delete it. If it does, the CmaxwellMxi destructur will crash.

Return value

C++

Crgb8 array of size = (xRes * yRes) containing the RGB preview image.

Python

NumPy ubyte array containing the RGB preview image. Shape is (xRes,yXres,3).

setPreview

Sets the scene preview image.

Parameters

Return value

Python

false = Error setting preview image.

true = Success.

isResumable

Check whether the MXI is resumable.

getSamplingLevel

Gets current MXI sampling level.

getRenderTimeInSeconds

Returns the total render time (including any resume render) in seconds. If the MXI was not generated through a render process but converting an image the method returns 0.

xRes

Image width.

yRes

Image height.

filmWidth

Camera film width (mm).

filmHeight

Camera film height (mm).

getIso

Gets ISO.

setIso

Sets ISO.

getShutter

Gets shutter.

setShutter

Sets shutter.

getFstop

Gets f-stop.

setFstop

Sets f-stop.

getExposure

Gets exposure.

setExposure

Sets exposure.

getBurn

Gets burn.

setBurn

Sets burn.

getMonitorGamma

Gets monitor gamma.

setMonitorGamma

Sets monitor gamma.

getSharpness

Gets sharpness.

setSharpness

Sets sharpness.

isSharpnessEnabled

Gets sharpness state.

setSharpnessEnabled

Sets sharpness state.

setColorSpace

Sets the color space for the MXI. Input parameter must be one of the COLOR_SPACES defined at sourcesenums.h.

Return value

0 = Error setting color space.

1 = Success.

getColorSpace

Gets the color space of the MXI. It returns one of the COLOR_SPACES defined at sourcesenums.h.

Return value

Python

Color space.

Examples

mxi = CmaxwellMxi();
if not mxi.read('c:/scenes/render.mxi').failed():
  colorspace = mxi.getColorSpace();
  if colorspace == COLOR_SPACE_SRGB:
    print("SRGB");

isDevignettingEnabled

Gets devignetting state.

setDevignettingEnabled

Sets devignetting state.

getDevignetting

Gets devignetting value.

setDevignetting

Sets devignetting value.

isDiffractionEnabled

Gets diffraction state.

setDiffractionEnabled

Sets diffraction state.

getDiffractionIntensity

Gets diffraction intensity value.

setDiffractionIntensity

Sets diffraction intensity value.

getDiffractionFrequency

Gets diffraction frequency value.

setDiffractionFrequency

Sets diffraction frequency value.

getApertureMap

Gets diffraction aperture map file name.

setApertureMap

Sets diffraction aperture map file name.

getObstacleMap

Gets diffraction obstacle map file name.

setObstacleMap

Sets diffraction obstacle map file name.

isScatteringEnabled

Gets scattering state.

setScatteringEnabled

Sets scattering state.

getScattering

Gets scattering value.

setScattering

Sets scattering value.

getCameraName

Gets the name of the camera used to generate the MXI.

getCameraCoordinates

Gets camera coordinates (position, target and up vectors).

Parameters

Return value

C++

false = Error getting camera coordinates (i.e., bad iStep parameter).

true = Success.

Python

Tuple containing the three output vectors.

getCameraFocalLenght

Gets camera focal lenght.

Parameters

Return value

C++

false = Error getting camera focal length (i.e., bad iStep parameter).

true = Success.

Python

Camera focal length.

getCameraFStop

Gets camera focal lenght.

Parameters

Return value

C++

false = Error getting camera f-stop (i.e., bad iStep parameter).

true = Success.

Python

Camera f-stop.

getCameraShutter

Gets camera shutter.

getCameraIso

Gets camera ISO.

getCameraDiaphragm

Gets camera diaphragm parameters.

Parameters

Return value

Python

Tuple containing the camera diaphragm parameters.

getCameraFps

Gets camera FPS.

getMultilightType

Returns the multilight type of the MXI.

• 0: No multilight
• 1: Intensity
• 2: Color + Intensity

getLightsCount

Returns the number of lights contained in the MXI. Environment is not considered.

getLightBuffersCount

Returns the number of lights buffers contained in the MXI, including environment data (Sun, physical sky, etc.). 

getLightsNames

Gets all light names.

Return value

C++

false = Error getting lights names.

true = Success.

Python

String list with the names. Empty string if error.

getLightName

Returns the name of the light with the given index. If the index is invalid an empty string is returned.

getLightIndex

Returns the index of the light with the given name. Returns -1 if there are no lights with this name.

getLightType

Returns the type of the light with the given index.

getLightIntensity

Returns the intensity of the light with the given index. Depending on the type the returned intensity means different things:

• If type is TYPE_COLOR_AND_LUMINANCE the intensity is the absolute emission value in the units used (watts, lumens, etc).
• If type is TYPE_TEMPERATURE the intensity is in kelvin.
• If type is anything else the returned intensity is a multiplier that affects the original emission value.
• If the index is invalid getLightIntensity returns -1.

setLightIntensity

Sets the intensity of the light with the given index.

Return value

0 = Invalid light index.

1 = Otherwise.

getLightColor

Returns the Crgb color of the light with the given index. This call makes sense only when LightType is TYPE_COLOR_AND_LUMINANCE and color type is set to rgb color. Otherwise getLightColor returns a white color.

setLightColor

Sets the Crgb color of the light with the given index. This call makes sense only when LightType is TYPE_COLOR_AND_LUMINANCE and color type is set to rgb color. Otherwise returns 0.

Return value

0 = Error.

1 = Success.

getLightTemperatureColor

Returns the temperature color in kelvins of the light with the given index. This call makes sense only when LightType is TYPE_COLOR_AND_LUMINANCE and color type is set to temperature color, otherwise -1.0 is returned.

setLightColor

Sets the temperature color in kelvins of the light with the given index. This call makes sense only when LightType is TYPE_COLOR_AND_LUMINANCE and color type is set to temperature color, otherwise 0 is returned.

Return value

0 = Error.

1 = Success.

getConstantSkyLuminance

Returns the constant sky luminance (in cd/m2).

Return value

C++

0 = There is no sky or it is not constant.

1 = Success.

Python

-1 = There is no sky or it is not constant.

Otherwise, constant sky luminance value.

setConstantSkyLuminance

Sets the constant sky luminance value.

Return value

0 = Error setting constant sky luminance value.

1 = Success.

getPhysicalSkyLuminance

Gets the physical sky luminance which is represented by the sun power factor in the scene.

Return value

C++

0 = There is no sky or it is not physical.

1 = Success.

Python

-1 = There is no sky or it is not physical.

Otherwise, physical sky luminance value.

setPhysicalSkyLuminance

Sets the physical sky luminance value.

Return value

0 = Error setting physical sky luminance value.

1 = Success.

getSunPowerFactor

Gets the sun power factor used when there is constant sky plus sun.

Return value

C++

0 = There is no sun in the scene.

1 = Success.

Python

-1 = There is no sun in the scene.

Otherwise, sun power factor.

setSunPowerFactor

Sets the sun power factor used when there is constant sky plus sun.

Return value

0 = Error setting sun power factor.

1 = Success.

getEnvironmentWeight

Gets the environment weight factor.

Return value

C++

0 = There is no environment in the scene.

1 = Success.

Python

-1 = There is no environment in the scene.

Otherwise, environment weight.

setEnvironmentWeight

Sets the environment weight.

Return value

0 = Error setting environment weight.

1 = Success.

loadEmixer

Reads the given emixer file and applies its settings to the MXI.

Parameters

Return value

false = Error loading emixer data.

true = Success.

saveEmixer

Saves the current MXI settings into an emixer file.

Return value

false = Error saving emixer file.

true = Success.

exportMultilightSettingsToScene

Imports the current MXI settings back into the MXS scene. This method assumes pMaxwell is valid and contains a valid scene.

Return value

false = Error saving emixer file.

true = Success.

read

Reads a MXI file from disk.

Parameters

Return value

Cerror::failed() = true: error reading MXI.

Cerror::failed() = false: success.

Examples

CmaxwellMxi* mxi = new CmaxwellMxi();
Cerror err = mxi->read("c:\\scenes\\myrender.mxi");
if( !err.failed() )
{
  // MXI readed successfully. 
}    

mxi = CmaxwellMxi();
err = mxi.read('c:/scenes/myrender.mxi');
if not err.failed():
  print("MXI readed successfully");   

write

Writes an MXI file to disk.

Return value

Cerror::failed() = true: error writting MXI.

Cerror::failed() = false: success.

getFileSize

Returns the number of bytes that this MXI will have, even if it has not been saved yet. It takes into account the buffers, channels and multilight options enabled.

readImage

Reads an image file and fills the Cmxi buffer with it.

Return value

false = Error reading image.

true = Success.

extractChannels

Extracts all the channels embeded in the MXI to disk.

Parameters

Return value

false = Error saving channels.

true = Success.

getLightBuffer

Returns a light buffer by index.

Parameters

Return value

C++

true = Buffer readed successfully.

false = Error getting light buffer.

Python

NumPy array containing the RGB image. Array dimensions: (height, width, 3).

Examples

void* buffer = NULL;
dword width, height;
char* name = new char[512];  
 
if( mxi->getLightBuffer( 0, 32, buffer, width, height, name, false ) )
{
  float* data = (float*) buffer;
  Crgb* rgb   = (Crgb*)  buffer;

  dword pixels = width * height;
  dword values = width * height * 3;
   
  for( dword i = 0; i < pixels; i++ )  
  {
    // Use the buffer.
    Crgb p = rgb[i];
    printf( "red:   %f\n", p.r );
    printf( "green: %f\n", p.g );
    printf( "blue:  %f\n", p.b ); 
  }

  for( dword i = 0; i < values; i++ ) 
  {
    // Use the buffer.
    float v = data[i];
    printf( "value: %f\n", v ); 
  }
      
}  

from numpy import *

image = mxi.getLightBuffer( 0, 32 ):

for i in range(0,image.size):
  print(image.flat[i]); 

getRenderBuffer

Returns the render buffer.

Parameters

Return value

C++

true = Buffer readed successfully.

false = Error getting render buffer.

Python

NumPy array containing the RGB image. Array dimensions: (height, width, 3). The type depends on the bit-depth requested: 8 (ubyte), 16 (ushort) or 32 (float).

getExtraBuffer

Returns an extra buffer by name.

Parameters

Return value

C++

true = Buffer readed successfully.

false = Error getting extra buffer.

Python

NumPy array containing the RGB image. Array dimensions: (height, width, 3 or 4).

getExtraBuffer

Returns an extra buffer by ID.

Parameters

Return value

C++

true = Buffer readed successfully.

false = Error getting extra buffer.

Python

NumPy array containing the RGB image. Array dimensions: (height, width, 3 or 4).

getShadowBuffers

Returns an array with all shadow buffers with the given bitDepth.

Parameters

Return value

C++

true = Buffers readed successfully.

false = Error getting shadow buffers.

Python

List containing all shadow buffers as NumPy arrays. Array dimensions: (height, width, 3).

getShadowBuffer

Returns a shadow buffer by index.

Parameters

Return value

C++

true = Shadow buffer readed successfully.

false = Error getting shadow buffer.

Python

NumPy array containing the RGB image. Array dimensions: (height, width, 3).

getNumberOfShadowBuffers

Returns the number of shadow buffers available.

• 0: No shadow buffer.
• 1: Shadow buffer available (1 emitter or no multilight).
• N: As many shadow buffers as light emitters.

getExtraBuffersEnabledMask

Returns a bitwise mask with the extra buffers rendered. See RENDER_CHANNELS (maxwellenums.h). Useful to check what extra channels are available in the MXI.

Examples

mxi = CmaxwellMxi();
mxi.read('sample.mxi');
mask = mxi.getExtraBuffersEnabledMask();
haveZ = mask & FLAG_Z;
if haveZ:
  print('Z channel is present');" 

createImages

Create N buffers of the given resolution.

setBufferRGB

Fills the selected image buffer with the given floating RGB buffer. This function recalculates the image buffer taking into account all the parameters as Iso, Shutter, etc.. so it assumes all of them are initialized to the proper values.

Parameters

updateDisplay

Updates the render image buffer and all the render channels.

updatePreview

Updates the preview buffer.

updateLightInPreview

Updates the given light in the preview buffer.

updateAllLightsInPreview

Updates all the lights in the preview buffer.

getPreviewResolution

Given a render resolution (xRes & yRes) returns the preview resolution.

Return value

Python

Tuple containing preview resolution (xResPreview,yResPreview).

getRenderPreviewBuffer

Returns the preview render buffer used for interactive purposes. The size of the buffer can be asked using getPreviewResolution.

Return value

C++

Crgb8 array containing the preview render image.

Python

NumPy array containing the preview render image. Shape is (width,height,3).

isMerged

Returns true if the MXI file is the result of a merge process and false if not.

getUsedIdCpusCount

Returns the number of MXIs used to generate this MXI if it is the result of a merge process. Returns 0 if the MXI was not generated through a merge process.

getUsedIdCpus

Fills an array with the cpu IDs (seeds) used to generate this MXI file. In C++, the caller is responsible of allocating and freeing the array after using it.

Return value

C++

0 = Error. The MXI was not generated through a merge process.

1 = Success.

Python

0 = Error. The MXI was not generated through a merge process.

Otherwise = int list containing the cpu IDs.

mergeMxis

Merges all the MXI files given in the sources array that contains all the paths to the mxis to merge.

Return value

0 = Error merging the MXIs.

1 = Success.

getEmixerVersion

Returns the emixer version file used in this version of the SDK.