通过数据集管理工程数据#

在VisionFlow中, 数据被分成: Parameter 参数和 Property 属性两种类型。本节会通过一些例子详细介绍如何访问、更新 property 属性类型的数据。

所有的属性数据 property 都被保存在数据库中并被组织成 SampleSet 数据集这种数据结构，通过高层接口的抽象隐藏了底层实现细节提升易用性。

通过 PropertySet 访问 Property #

PropertySet是一个管理样本集中所有样本的单个同一属性数据的数据结构。样本集中所有样本的某个属性都存储在属性集中。

PropertySet同时还记录了所有样本的该属性的最后更新时间。

Note

与SampleSet类似，PropertySet同样也维护了一个数据库句柄，PropertySet析构时也会减少数据库的引用计数。

PropertySetIterator#

与SampleSet类似，PropertySet同样也提供了迭代器类型： visionflow::data::PropertySetIterator。

以下示例代码展示了如何通过PropertySetIterator迭代获取样本集中所有样本的图片属性：

C++

// get the PropertySet of Image
visionflow::data::PropertySet property_set = sample_set.property_set({"Input", visionflow::Input::image});

for (auto iter = property_set.begin(); iter.valid(); ++iter) {
    std::cout << "sample id :" << iter.key() << std::endl;

    // convert to props::Image ptr
    auto img = iter.value()->as<visionflow::props::Image>();
    // use img property to do some work ...
}

Python

.. TODO

.. TODO

访问和修改PropertySet中的属性#

你可以通过样本id或者PropertySetIterator来访问或修改更新属性集中的属性。

Warning

样本id必须在样本集中存在，否则会抛出异常 visionflow::excepts::SampleNotFound .

PropertySetIterator必须指向属性集中存在的属性，否则会抛出异常 visionflow::excepts::InvalidIterator .

以下示例代码展示了如何更新属性集中的图片属性：

C++

// get the PropertySet of Image
visionflow::data::PropertySet property_set = sample_set.property_set({"Input", visionflow::Input::image});

// get last update time
std::cout << "last time:" << property_set.last_update_time();

// get property type
assert(property_set.property_type() == "visionflow::props::Image");

// check sample not empty
assert(property_set.sample_empty() == false);
assert(property_set.data_exists(1) == true);

// get image property by sample id
auto img_of_sample_1 = property_set.at(1);

// reset a new image to the image property
img_of_sample_1->set_image(visionflow::img::Image::FromFile("D:/path/to/new_img.jpg"));

// update PropertySet by sample id
property_set.update(1, *img_of_sample_1);

// erase PropertySet by iterator
const auto&iter = property_set.find(4);
property_set.erase(iter);

// now the image property in sample 4 will be erased

Python

.. TODO

.. TODO

WriteBatch提供更好的性能#

由于每次将样本的修改更新到数据库都会引发磁盘I/O，因此频繁的更新将会花费很多性能开销。

我们提供WriteBatch批量更新功能，允许将多次修改缓存到内存中，最后将这些修改一次性的更新到数据库并落盘，减少频繁的数据库访问以提升性能。

PropertyWriteBatch#

PropertyWriteBatch缓存所有对属性集的修改操作。

Note

对于同一个样本，只有最后的修改会生效(之前缓存的修改将被覆盖)。

Warning

你需要确保被修改的样本存在于样本集中，否则在更新PropertyWriteBatch时会抛出异常 visionflow::excepts::SampleNotFound 。

以下示例代码展示了如何使用 PropertyWriteBatch 批量更新属性集：

C++

// get the PropertySet of Image
visionflow::data::PropertySet property_set = sample_set.property_set({"Input", visionflow::Input::image});

// firstly, create a PropertyWriteBatch
PropertyWriteBatch prop_write_batch = property_set.create_write_batch();

// catch all your modification on image PropertySet for different samples

// update sample 1 with img_101
visionflow::props::Image img_101;
img_101.set_image(visionflow::img::Image::FromFile("D:/path/to/img_101.jpg"));
prop_write_batch.update(1, img_101);

// update sample 2 with img_102
visionflow::props::Image img_102;
img_102.set_image(visionflow::img::Image::FromFile("D:/path/to/img_102.jpg"));
prop_write_batch.update(2, img_102);

// erase image property in sample 3
prop_write_batch.erase(3);

// erase image property in sample 2
// this will overwrite previous update operator
prop_write_batch.erase(2);

// update to database at once
property_set.write_batch(prop_write_batch);

// now all the modification are update to database
// image property in:
//          sample 1 will update to img_101;
//          sample 2 and sample 3 will be erased;

Python

.. TODO

.. TODO

SampleWriteBatch#

SampleWriteBatch缓存了所有对样本集的修改操作，例如更新整个样本数据、更新某个样本里的某个属性数据或是更新样本描述信息。

Note

同样的，对于同一个样本的同一个数据，只有最后的修改会生效(之前缓存的修改将被覆盖)。

Warning

你需要确保被修改的样本存在于样本集中，否则在批量更新SampleWriteBatch时会抛出异常 visionflow::excepts::SampleNotFound 。

以下示例代码展示了如何使用 SampleWriteBatch 批量更新样本集：

C++

// firstly, create a SampleWriteBatch
SampleWriteBatch sample_write_batch = sample_set.create_write_batch();

const visionflow::ToolNodeId img_prop_id = {"Input/image"};

// catch all your modification to SampleWriteBatch

// update sample 1 with img_101
visionflow::props::Image img_101;
img_101.set_image(visionflow::img::Image::FromFile("D:/path/to/img_101.jpg"));
sample_write_batch.update(
    1, img_prop_id, std::make_shared<visionflow::props::Image>(img_101));

// update sample 2 with img_102
visionflow::props::Image img_102;
img_102.set_image(visionflow::img::Image::FromFile("D:/path/to/img_102.jpg"));
sample_write_batch.update(
    2, img_prop_id, std::make_shared<visionflow::props::Image>(img_102));

// erase in sample 3
sample_write_batch.erase(3);

// erase image property in sample 2
// this will overwrite previous update operator
sample_write_batch.erase(2, img_prop_id);

// update to database at once
sample_set.write_batch(sample_write_batch);

// now all the modification are update to database
// image property in:
//          sample 1 will update to img_101;
//          sample 2 will be erased;
// and the whole sample 3 will be erased from SampleSet;

Python

.. TODO

.. TODO

ConfigureRuntimeProjectFilterAdapter#

ConfigureRuntimeProjectFilterAdapter 是在 Configure（训练/统计）流程 中使用的数据过滤适配器，通过 filter_adapt 工厂函数创建。它将 Project 与 ConfigureRuntime 连接起来，允许在不修改数据库原始数据的前提下，控制算法服务所能看到的数据范围。

与 ReadOnlyPropertySetView 的区别：

ReadOnlyPropertySetView 用于 通用数据读取，直接从 PropertySet 构建过滤视图；
ConfigureRuntimeProjectFilterAdapter 用于 Configure 流程，过滤结果透明传入算法服务，算法无需感知过滤的存在。

示例：分割工具的混淆矩阵计算

以分割工具为例：Segmentation::statistician 配置器负责计算混淆矩阵（精确率、召回率等指标），其统计范围由 Segmentation::tagged_views 属性中的 ViewList 决定。

样本的 ViewList 中，每个视图除了有 kTest / kTrain 分集标签外，还可以附加用户自定义标签（如 "front_face"、"back_face"）来区分拍摄位置等信息。

默认情况下，Segmentation::statistician 会统计所有视图。如果只想评估某个特定拍摄位置的模型效果，就需要将统计范围收窄到含有该标签的视图子集。

不设置过滤：所有视图均参与统计

C++

// #include "visionflow/node_names.hpp" 包含各工具节点名的常量定义
const visionflow::ToolNodeId tagged_views_id{segment_id, visionflow::Segmentation::tagged_views};
const visionflow::ToolNodeId statistician_id{segment_id, visionflow::Segmentation::statistician};
const visionflow::ToolNodeId statistics_id{segment_id, visionflow::Segmentation::statistics};

auto config_rt = proj->create_config_runtime(statistician_id, opts);
auto adapter = visionflow::filter_adapt(proj.get(), config_rt);

// 不设置任何过滤，kTest 和 kTrain 的所有视图均参与统计
config_rt.initialize(adapter);
config_rt.execute(adapter);
adapter.commit();

const auto &metrics =
    proj->get_param(statistics_id)->as<visionflow::param::ModelEvaluationMetrics>();
// metrics.table(kTestView) 包含所有 kTest 视图的统计结果
// metrics.table(kTrainView) 包含所有 kTrain 视图的统计结果

Python

.. TODO

使用 MakeViewTagFilterScript 收窄统计范围

MakeViewTagFilterScript 根据指定标签自动生成过滤脚本，将 Segmentation::tagged_views 裁剪为只含有 同时满足所有指定标签 的视图，无需手写 Python：

C++

auto config_rt = proj->create_config_runtime(statistician_id, opts);
auto adapter = visionflow::filter_adapt(proj.get(), config_rt);

// 只统计带有 "front_face" 标签的视图，忽略其他拍摄位置的视图
visionflow::Tags filter_tags;
filter_tags.add("front_face");
adapter.set_filter_script(
    tagged_views_id,
    visionflow::ConfigureRuntimeProjectFilterAdapter::MakeViewTagFilterScript(
        filter_tags));

config_rt.initialize(adapter);
config_rt.execute(adapter);
adapter.commit();

const auto &metrics =
    proj->get_param(statistics_id)->as<visionflow::param::ModelEvaluationMetrics>();
// metrics.table(kTestView) 只包含带 "front_face" 标签的 kTest 视图
// 不含该标签的视图（如 "back_face"）被排除在统计之外

// 传入空 Tags 时，MakeViewTagFilterScript 返回空字符串，等同于不过滤
visionflow::Tags empty_tags;
assert(visionflow::ConfigureRuntimeProjectFilterAdapter::MakeViewTagFilterScript(
           empty_tags).empty());

Python

.. TODO

使用 set_filter_ids 排除指定样本

在样本层面直接排除指定 id，无论其视图内容如何，被排除的样本对算法完全不可见：

C++

auto adapter = visionflow::filter_adapt(proj.get(), config_rt);

// 排除已知质量不佳的样本
adapter.set_filter_ids({5, 10, 23});

config_rt.initialize(adapter);
config_rt.execute(adapter);
adapter.commit();

Python

.. TODO

综合示例：set_filter_ids + MakeViewTagFilterScript

两者可叠加——先按 id 排除不参与统计的样本，再按视图标签收窄统计范围：

C++

auto config_rt = proj->create_config_runtime(statistician_id, opts);
auto adapter = visionflow::filter_adapt(proj.get(), config_rt);

// 1. 排除异常样本
adapter.set_filter_ids({5, 10});

// 2. 只统计 "front_face" 拍摄位置的视图
visionflow::Tags filter_tags;
filter_tags.add("front_face");
adapter.set_filter_script(
    tagged_views_id,
    visionflow::ConfigureRuntimeProjectFilterAdapter::MakeViewTagFilterScript(
        filter_tags));

config_rt.initialize(adapter);
config_rt.execute(adapter);
adapter.commit();

// 查看收窄统计范围后的混淆矩阵指标
const auto &metrics =
    proj->get_param(statistics_id)->as<visionflow::param::ModelEvaluationMetrics>();

Python

.. TODO

关于 ConfigureRuntimeProjectFilterAdapter 的更多信息，请查看 visionflow::ConfigureRuntimeProjectFilterAdapter 。

通过数据集管理工程数据#

通过数据集 SampleSet 获取数据 Sample #

LazySample和Sample#

LazySample#

Sample#

查看Sample中存放的属性#

SampleSetIterator#

SampleDescriptor#

更新SampleDescriptor#

添加Sample#

更新Sample#

移除sample#

通过 PropertySet 访问 Property #

PropertySetIterator#

访问和修改PropertySet中的属性#

WriteBatch提供更好的性能#

PropertyWriteBatch#

SampleWriteBatch#

数据过滤#

ReadOnlySampleSetView#

ReadOnlyPropertySetView#

ReadOnlyPropertySetView 过滤详解（以 ViewList 属性为例）#

ConfigureRuntimeProjectFilterAdapter#

通过数据集管理工程数据#

通过数据集 SampleSet 获取数据 Sample#

LazySample和Sample#

LazySample#

Sample#

查看Sample中存放的属性#

SampleSetIterator#

SampleDescriptor#

更新SampleDescriptor#

添加Sample#

更新Sample#

移除sample#

通过 PropertySet 访问 Property#

PropertySetIterator#

访问和修改PropertySet中的属性#

WriteBatch提供更好的性能#

PropertyWriteBatch#

SampleWriteBatch#

数据过滤#

ReadOnlySampleSetView#

ReadOnlyPropertySetView#

ReadOnlyPropertySetView 过滤详解（以 ViewList 属性为例）#

ConfigureRuntimeProjectFilterAdapter#

通过数据集 SampleSet 获取数据 Sample #

通过 PropertySet 访问 Property #