Skip to main content

Capture

Introduction​

This tutorial explains how to use the SizectorS_SDK to capture point clouds and TIFF images.

For Linux, please see the tutorial.

tip

If you prefer watching video tutorials, our webinar 'Making 3D captures easy' covers the same content as this capture tutorial.

Prerequisites​

  • Install the SizectorS software.

Initialization​

Initializing a Sensor instance and keeping it active during program execution is necessary to call any API in SizectorS_SDK.

IMPSizectorS *Sensor = MPSizectorS_Factory::GetInstance(MPSizectorS_LogMediaType_CallBack);

Set the locale for all categories of the current program to English language, United States region, and UTF-8 encoding.

setlocale(LC_ALL, "");

Connection​

Viewing Cameras​

You can also list all cameras connected to the computer and view their serial numbers and related information.

int DeviceCount = Sensor->GetDeviceCount();
for(int i = 0; i < DeviceCount; i++)
{
    DeviceInfo = Sensor->GetDeviceInfo(i);
    printf("Device #%d :\r\n", i);
    wprintf(L"  -Name : %s\r\n", DeviceInfo.DeviceName);
    wprintf(L"  -Serial Number : %s\r\n", DeviceInfo.DeviceSerialNumber);
    printf("  -Is Activated : %s\r\n", DeviceInfo.IsActivated ? "True" : "False");
    printf("  -HW Version : %.2f\r\n", (float)DeviceInfo.HWVersion);
    printf("  -FW Version : %.2f\r\n", (float)DeviceInfo.FWVersion);
    printf("  -Minimum SDK Version : %.2f\r\n", DeviceInfo.MinimumSDKVersion);
    printf("  -Sensor Width : %d\r\n", DeviceInfo.SensorWidth);
    printf("  -Sensor Height : %d\r\n", DeviceInfo.SensorHeight);
    printf("  -Sensor Resolution : %d\r\n", DeviceInfo.SensorResolution);
    printf("  -Binning Possibility : %s\r\n", DeviceInfo.BinningPossibility ? "True" : "False");
    printf("  -Sensor Binning Width : %d\r\n", DeviceInfo.SensorBinningWidth);
    printf("  -Sensor Binning Height : %d\r\n", DeviceInfo.SensorBinningHeight);
    printf("  -Sensor Binning Resolution : %d\r\n", DeviceInfo.SensorBinningResolution);
    printf("  -X Max : %.2f\r\n", DeviceInfo.XMax);
    printf("  -Y Max : %.2f\r\n", DeviceInfo.YMax);
    printf("  -Z Max : %.2f\r\n", DeviceInfo.ZMax);
    printf("  -Device Interface : %s\r\n", (DeviceInfo.InterfaceType == MPSizectorS_InterfaceType_U2) ? "USB2.0" : ((DeviceInfo.InterfaceType == MPSizectorS_InterfaceType_U3) ? "USB3.0" : "EtherNet"));
}

Setting Callback Functions​

Set log callback function, device state change callback function, and data callback function.

if (SHOW_LOG) Sensor->SetLogCallBack(LogCallBack);
Sensor->SetDeviceStateChangeCallBack(&DeviceStateChangeCallBack);
Sensor->SetDataCallBack(DataCallBack);

Selecting a Camera​

When multiple cameras are connected to the same computer, if you need to use a specific camera in the code, you can do so by the serial number of that camera.

Sensor->Open(Sensor->GetDeviceInfo(choice));

Capture settings should be initialized as follows, but you are free to change the processing settings.

Sensor->SetTriggerSource(MPSizectorS_TriggerSourceType_SoftTriggerOnly);
Sensor->SetHoldState(false);
Sensor->SetAutoReconnect(true);
Sensor->SetExposureIntensity2D(10);
Sensor->SetExposureIntensity3D_1st(5);
Sensor->SetExposureIntensity3D_2nd(10);
Sensor->SetExposureIntensity3D_3rd(20);
Sensor->SetUserGain(0);

Configuration​

Like all other cameras, the SizectorS camera has configurable parameters. These parameters can be set manually.

Manual Settings​

Another option is to configure settings manually. For more information about what each setting does, please see Camera Settings.

Setting Pixel Merging​

Sensor->SetBinningState(false); //Turn off pixel merging
Sensor->SetBinningState(true);  //Turn on pixel merging

Setting Capture Mode​

Sensor->SetWorkingMode(MPSizectorS_WorkingModeType_3D_Fast); /// Fast 3D mode
Sensor->SetWorkingMode(MPSizectorS_WorkingModeType_2D_White); /// Full white illumination 2D mode

Sensor->SetDataOutMode(MPSizectorS_DataOutModeType); // Floating-point point cloud 3D data mode. X, Y, Z are represented by 32-bit floating numbers

Sensor->SetTriggerSource(MPSizectorS_TriggerSourceType_SoftTriggerOnly); /// Receive software triggers only.
Sensor->SetTriggerSource(MPSizectorS_TriggerSourceType_KeepRunning); /// Continuous shooting, automatically starts the next capture after one is complete.
info

When setting to 2D working mode, SetDataOutMode is not necessary.

Loading​

SizectorS_SDK can save the current settings to an .mpur file. These can be read and applied in the API. You might find it easier to modify these settings in your favorite editor, as they are human-readable in the mpur file.

char* chrArrSN = "Setting";
const char* cfgSuffix = ".mpur";
std::string fileName = std::string(chrArrSN) + cfgSuffix;
auto retRead = Sensor->ReadAllConfigFromFile((char*)fileName.c_str());
printf("\r\n Device [%s] ReadAllConfigure result is %s \r\n", chrArrSN, retRead ? "SUCCESS" : "FAILED");

Saving​

You can also save the settings to an .mpur file.

char* chrArrSN = "Setting";
const char* cfgSuffix = ".mpur";
std::string fileName = std::string(chrArrSN) + cfgSuffix;
auto retWrite = Sensor->WriteAllConfigToFile((char*)fileName.c_str());
printf("\r\n WriteAllConfigToFile result is %s \r\n", retWrite ? "SUCCESS" : "FAILED");
printf("\r\n Configurations is saved to [%s%s] \r\n\r\n", chrArrSN, ".mpur");

Setting Default Configuration​

You can also set the default mode, saved in FlashROM, which will be called when the device is powered on.

auto retSave = Sensor->SaveSettingsAsDefault();
printf("\r\n SaveSettingsAsDefault result is %s \r\n\r\n", retSave ? "SUCCESS" : "FAILED");;

Capturing​

Now we can capture 2D or 3D images.

MPSizectorS_DataFormatType DataFormat; Contains data format with capture information.
MPSizectorS_DataFrameUndefinedStruct Data; Contains point clouds and color images (stored in computing device memory) along with capture and camera information.

Capturing Images​

If we want to capture images, we can do so through the API.

Sensor->Snap(true, &DataFormat, &Data, 100);

Loading​

After saving, images can be loaded from an mpdat file.

const auto dataFile = std::string(ZIVID_SAMPLE_DATA_DIR) + "/SizectorS.mpdat";
std::cout << "Reading MPDAT frame from file: " << dataFile << std::endl;
MPSizectorS_Utils::Load(&Data, dataFile);

This tutorial will explain later how to save to an mpdat file.

Saving​

We can now save the results.

const auto dataFile = "Frame.mpdat";
MPSizectorS_Utils::Save(Data, dataFile);
tip

You can open and view the Frame.mpdat file in MPSizectorS_ControlCenter.

Exporting​

API detects the format to use. See Point Cloud for a list of supported formats. For example, we can export the point cloud in .ply or .pcd format.

const auto dataFile = "PointCloud.ply";
MPSizectorS_Process_SavePLY(Data, dataFile);

const auto dataFile = "PointCloud.pcd";
MPSizectorS_Process_SavePCD(Data, dataFile);

Saving TIFF Images​

We can obtain TIFF type images from the capture and save them.

const auto dataFile = "PointCloud.tiff";
MPSizectorS_Process_SaveTIFF(Data, true, dataFile, true);

Conclusion​

This tutorial demonstrates how to use the MPSizectorS SDK for camera connection, configuration, capturing, and file saving.