Helper Utilities#

Input Helper#

Input helper is a tool to help user import list of images into the sample set from filesystem or add image into sample at inference.

void visionflow::helper::add_image_to_sample(ISample &sample, const Image &image, const std::string &input_tool_id, bool with_fingerprint = false, size_t thumbnail_long_side = 0)#

Add an image into the sample with the given Input tool id. This is just a user-friendly helper function, which is a simple encapsulation of the ISample interface. Users can also achieve the functionality provided by this function through the interface of the Sample object themselves, as shown in the code example below:

sample.get_or_create<props::Image>({input_tool_id, "image"})
    ->set_image(image);
sample
    .get_or_create<props::ViewList>({input_tool_id, "views"})
    ->add(
        TaggedView{{geometry::Matrix3f(1), geometry::Size2f{image.size()}}});
sample
    .get_or_create<props::RawImageInfo>(
        {input_tool_id, "image_info"})
    ->set_info_from_image(image, with_fingerprint, thumbnail_long_side);

Parameters:

sample – The sample to add the image into.
image – image to be added in.
input_tool_id – The Input tool id.
with_fingerprint – Save the image fingerprint or not. Typically, when importing images into the project, you should set this parameter to True. When deploying to a production environment, you can set this parameter to False to skip computing image fingerprints and improve speed.
thumbnail_long_side – The thumbnail long side length. If not specified, the thumbnail size will be zero and the thumbnail image will be empty.

struct InputHelperOptions#

The options for InputHelper.

Public Members

std::string sample_set_name = {}#: The name of sample_set, which will be the name of the main dataset of the project when it is empty or using the default value.

std::string input_tool_id = {}#: The Input tool name. If set to empty or using the default value, the importer will automatically look for the name of the Input tool in the project. If there is no Input tool or multiple Input tools in the project, an exception will be thrown. If the given tool name is not empty, you need to ensure that the tool exists and its type is “Input”, otherwise an exception will also be thrown.

bool auto_deduplication = true#: Whether to remove duplicate images automatically. When this option is set to true, the InputHelper will automatically removes duplicate images that are identical based on the fingerprint of the image, and images that have been previously imported into the dataset will not be re-imported too.

util::IProgressCallback *callback = nullptr#: The progress callback for importing the image.

size_t parallel_size = 0#: The number of threads to import images in parallel. The default value is 0. When set to 0, the executor will make an intelligent decision on the number of threads to parallelize. Generally, the default value of 0 is sufficient.

Tags tags = {}#: All samples imported by the InputHelper will be tagged with the given tags.

class InputHelper#

Utility for helping importing images into Input tool.

The common usage:

visionflow::helper::InputHelperOptions options;
options.input_tool_id = "InputTool";
visionflow::helper::InputHelper helper(project_ptr, options);
helper.add_images({image_files_path});
receipts = helper.commit();
for(const auto &receipt : receipts) {
    if(!receipt.is_success) {
        std::cout << receipt.error_message << std::endl;
    }
}

Get more option details in the InputHelperOptions.

Public Functions

const InputHelperOptions &options() const#

Get the final options information.

Returns:: const InputHelperOptions&

void add_image(const std::string &image_file)#

Record the image you want to add.

Parameters:: image_file – An image of a file

void add_image(const std::vector<std::string> &image_files)#

Record the image you want to add.

Parameters:: image_files – An image of multiple files

void add_images(const std::vector<std::string> &images_files)#

Record the images you want to add.

Parameters:: images_files – Multiple images, each consisting of a file.

void add_images(const std::vector<std::vector<std::string>> &images_files)#

Record the images you want to add.

Parameters:: images_files – Multiple images composed of multiple files.

const std::vector<InputHelper::Receipt> &commit()#

Adds the currently recorded image to input tool.

Note

1.The image needs to meet the input parameter requirements. 2.When an image is added, channel 4 is converted into channel 3 and channel 2 is converted into channel 1.

Returns:: const std::vector<InputHelper::Receipt>& Receipt information returned after importing the images, ordered by the order in which the images were added.

struct Receipt#

Receipt information returned after importing the images.

Public Members

std::vector<std::string> image_files#: File path in image.

bool is_success = false#: Check whether the image is successfully imported.

uint32_t sample_id#: Import image returns sample_id, if failed sample_id is 0.

std::string error_message#

Error infomation, json format, always contains “type” and “message” fields.

some common error will be like:

The image is duplicated with someone in the dataset or add same image multiple times:
```
{
    "type": "ImageDuplicated",
    "message": "The image already exists in the dataset.",
    "duplicate_sample": 123
}
```
Note that the “duplicate_sample” field will be 0 if the image is duplicated with someone added into this InputHelper instance multiple times.

The image visual size is not match with the parameter requirements:

{
    "type": "InvalidImageVisualSize",
    "message": "The visual_size is required to be {}, but get {}."
}

Other errors, always contains “type” and “message” fields.

Third Party Label Format#

class LabelImg#

Public Functions

props::PolygonRegionList regions()#

Get LabelImg regions.

Returns:: props::PolygonRegionList

class LabelMe#

Public Functions

props::PolygonRegionList regions()#

Get LabelMe regions.

Returns:: props::PolygonRegionList

class Aqlabel#

Aqlabel import label.

Public Functions

explicit Aqlabel(const std::string &aqlabel_path)#

Constructor to set Aqlabel file path.

Parameters:

aqlabel_path – Aqlabel file path.

Throws:

visionflow::excepts::FileNotFound – If the file is not found.
visionflow::excepts::InvalidFileFormat – If the file is not Aqlabel.
visionflow::excepts::CanNotOpenFile – If the Aqlabel file cannot be opened.
visionflow::excepts::DeSerializeFailed – If failed to parse Aqlabel.

visionflow::props::PolygonRegionList regions() const#

Get Aqlabel regions.

Returns:: visionflow::props::PolygonRegionList Generally used as tool truth.

visionflow::props::PolygonRegionList specific_regions() const#

Get Aqlabel specific regions.

Returns:: visionflow::props::PolygonRegionList Generally used as tool hard_case or no_train.

std::string tool_type() const#

Get Aqlabel tool type.

Returns:: std::string Tool type.

GPU Device Information#

We provide some interface to help to get the GPU information.

struct GpuDriverInfo#

The structure of GPU driver information.

Public Members

std::string driver_version#: The GPU driver version.

std::string nvml_version#: NVML library version.

struct GpuDeviceConstInfo#

The constant information of a gpu device, and you can get them only once as it will not be changed in running time.

Public Members

size_t device_id#: The device id, start from 0.

std::string uuid#: The uuid of the gpu, such as “e6e9f9e0-c9c7-4e9e-b7a7-9d9f7c9e5f4f”.

std::string device_name#: The gpu name, such as “GeForce GTX 1060 Ti”.

std::string architecture#: The GPU architecture, one of [Kepler, Maxwell, Pascal, Volta, Turing, Ampere, Ada, Unkown].

std::string driver_mode#: The gpu driver mode, the value should be one of “TCC”(Tesla Compute Cluster) and “WDDM”(Windows Display Driver Model).

Note

Only available on Windows, it will be empty on linux.

size_t total_memory#: Total available gpu memory.

struct GpuDeviceDynamicInfo#: The dynamic information of a gpu device, which will be changed in the running time.

GpuDriverInfo visionflow::helper::get_gpu_driver_info()#

Get GPU device information.

Returns:: GpuDriverInfo

std::vector<GpuDeviceConstInfo> visionflow::helper::get_gpu_device_const_info()#

Get the gpu device const information, include the gpu id, name and memory, etc.

Returns:: std::vector<GpuDeviceConstInfo> The vector of gpu device information, each element represent a gpu device.

std::vector<GpuDeviceDynamicInfo> visionflow::helper::get_gpu_device_dynamic_info()#

Get the gpu device dynamic information. such as memory usage, etc.

Returns:: std::vector<GpuDeviceDynamicInfo> The vector of gpu device information.

Datapack-Project Transition#

struct DatapackExportOptions#

Options to export data from project to datapack.

Public Members

std::vector<uint32_t> sample_ids = {}#: Sample ids in the project to be export to the datapack.

bool export_all_samples = false#: Export all samples in the project. The sample_ids field will be ignored if this option is enabled.

std::string input_tool_id = {}#: The Input tool name. If the input tool name is empty, it will attempt to automatically search for the input tool name. If there are multiple input tools in the project, an exception will be thrown.

std::string sample_set_name = {}#: The sample_set name to export data from, which will be the name of the main dataset of the project when it is empty or using the default value.

bool with_image = false#: export the image data or not.

std::vector<ToolNodeId> property_ids = {}#: Data label or vie w data node id to be export into the datapack.

std::string remark = {}#: Customized datapack remark.

util::IProgressCallback *progress_callback = nullptr#: Callback function to report the export progress.

uint64_t max_pending_size = 0ULL#: Maximum size in bytes of in-memory data cache. When pending data exceeds this limit, extra data will be cached on disk. If set to 0 (default behavior), all data will be cached in memory until free memory less than 1GB.

struct DatapackImportOptions#

Options to import data from datapack to project.

Public Members

std::vector<uint32_t> sample_ids = {}#: Sample ids in the datapack to be import into the project.

bool import_all_samples = false#: Import all samples in the datapack. The sample_ids field will be ignored if this option is enabled.

std::string input_tool_id = {}#: The Input tool name. If the input tool name is empty, it will attempt to automatically search for the input tool name. If there are multiple input tools in the project, an exception will be thrown.

std::string sample_set_name = {}#: The sample_set name to import data to, which will be the name of the main dataset of the project when it is empty or using the default value.

std::map<ToolNodeId, std::string> property_column_map#: Data label or view data node id to be import into the project. The key is the property node id in the project, and the value is one of the column id in the data pack. Do not map label data to a view property or map view data to a label property.

bool only_import_for_exist_sample = false#: Only import the label or view data for the sample which already exist in the project. With this options enabled, all the sample which not exist in the project will be ignored.

bool force_replace_old_data = false#: Force replace the old label or view data in project with the data from the datapack. With this options enabled, the label or view data of the target properties will be replaced by the data from the datapack. And set this option to false, the data in the datapack will be ignored if the label or view data already exist in the target property node and the target sample.

bool import_as_new_sample_for_all = false#: Force create a new sample for every entry in datapack. If enabled, every selected datapack sample will be imported as a new sample without checking duplication, only_import_for_exist_sample will be ignored.

bool import_sample_descriptor_tags = false#: Import the sample descriptor tags from export source when creating new samples. If enabled, when a new sample is created, the tags field of new sample’s sample descriptor will be set to the tags stored in datapack.

bool auto_update_label_classes = true#: Try to update label classes parameter in the tool after import labels or not.

util::IProgressCallback *progress_callback = nullptr#: Callback function to report the import progress.

std::map<uint32_t, uint32_t> visionflow::helper::export_project_to_datapack(const Project &proj, const std::string &datapack_path, DatapackExportOptions options)#

Export data from project to a datapack.

Parameters:

proj – the project.
datapack_path – Utf-8 encoded datapack file path, which should be end with suffix “.vfpack”.
options – the export options.

Returns:

std::map<uint32_t, uint32_t> map of sample-id and datapack-id.

std::map<uint32_t, uint32_t> visionflow::helper::import_datapack_to_project(const visionflow::datapack::DataPack &datapack, Project &proj, DatapackImportOptions options)#

Import data from datapack to project.

Parameters:

datapack – the opened data package object.
proj – The project to import data into.
options – The import options.

Returns:

std::map<uint32_t, uint32_t> map of datapack-id and sample-id.

License Information#

std::string visionflow::helper::license_devices()#

Get all license devices.

Throws:

excepts::LicenseError – Failed to get license info.

Returns:

The all license devices.

[
 {
   "developer_id": "0800000000001b14",
   "host_name": "DESKTOP-*",
   "lm": "pub",
   "lock_info": {},
   "sn": "9733c8010007020056de000f000a0023",
   "type": "local"
 },
 {
   "developer_id": "0800000000001b14",
   "host_name": "DESKTOP-*",
   "ip": "192.168.102.*",
   "lm": "pub",
   "lock_info": {},
   "port": 10334,
   "sn": "9733c8010007020056de000f000a0023",
   "type": "remote"
 },
 {
   "account_name": "SC1072000000024",
   "developer_id": "0800000000001b14",
   "host_name": "DESKTOP-*",
   "ip": "",
   "lm": "pub",
   "port": 0,
   "type": "slock",
   "user_guid": "ce875d1ac5fb438399d0cb3d6d5d1d63"
 },
 {
   "account_name": "SC1072000000024",
   "developer_id": "0800000000001b14",
   "host_name": "DESKTOP-*",
   "ip": "192.168.102.*",
   "lm": "pub",
   "port": 10334,
   "type": "remote_slock",
   "user_guid": "ce875d1ac5fb438399d0cb3d6d5d1d63"
 }
]

std::string visionflow::helper::license_contents(const std::string &license_device)#

Get all license contexts with the license device. You can get all license devices license_devices and take out one of them.

Parameters:

license_device – license_devices

Throws:

excepts::LicenseError – Failed to get license contexts.

Returns:

All license contexts of the license device.

{
 "AIDI": {
   "2.3": {
     "feature_contexts": [
       {
         "license_id": 1,
         "feature_name": "Segment/Infer",
         "enable": true,
         "start_time": 1405608497,
         "end_time": 1428842731,
         "first_use_time": 1405608497,
         "span_time": 23234234,
         "counter": 25,
         "concurrent": 123,
         "concurrent_type": "win_user_session / process",
         "version": 342512,
         "last_update_timestamp": 42342525,
         "last_update_timesn": 2342,
         "lock_time": 23542532,
         "lic_status": {
           "status": 0,
           "message": "NORMAL / WILL EXPIRE / EXPIRE / USE UP"
         }
       },
       {
         "license_id": 1,
         "feature_name": "Segment/Infer"
       }
     ],
     "ext": {
       "SpeedLevel": 2
     }
   },
   "2.4": {}
 },
 "VisionFlow": {}
}

std::string visionflow::helper::license_sessions(const std::string &license_device)#

Get all license sessionses with the license device.

Parameters:

license_device – license_devices

Throws:

excepts::LicenseError – Failed to get sessions contexts.

Returns:

The license sessionses.

[
 {
  "license_id": 1,
  "sessions": [
    {
      "session_id": 1,
      "process_id": 18988,
      "win_session_id": 1,
      "process_name": "***",
      "computer_name": "DESKTOP-*",
      "license_id": 1,
      "ip": "192.168.102.*",
      "time_stamp": 1687833294
    }
  ]
},
{
  "license_id": 3,
  "sessions": [
    {
      "session_id": 2,
      "process_id": 18988,
      "win_session_id": 1,
      "process_name": "***",
      "computer_name": "DESKTOP-*",
      "license_id": 3,
      "ip": "192.168.102.*",
      "time_stamp": 1687833294
    }
  ]
}
]