distributed_heightfield_data.cpp

Go to the documentation of this file.

/******************************************************************************
 * Copyright 2023 NVIDIA Corporation. All rights reserved.
 *****************************************************************************/
 
#include <iostream>
#include <limits>
#include <sstream>
#include <vector>
 
#include <mi/dice.h>
 
// Include code shared by all examples.
#include "utility/example_shared.h"
 
#include <nv/index/icamera.h>
#include <nv/index/iconfig_settings.h>
#include <nv/index/idistributed_data_access.h>
#include <nv/index/iindex.h>
#include <nv/index/ilight.h>
#include <nv/index/imaterial.h>
#include <nv/index/iscene.h>
#include <nv/index/isession.h>
 
#include <nv/index/app/index_connect.h>
#include <nv/index/app/string_dict.h>
#include <nv/index/app/idata_analysis_and_processing.h>
 
/*
 
General Distributed Computing Concepts
======================================
NVIDIA IndeX distributes data in the cluster environment according to some distribution scheme.
As a result, the data cannot be accessed nor edited locally on a single machine.
NVIDIA IndeX has introduced general concepts that allow determining the locality of
distributed data as well as accessing and editing the distributed data.
 
The data locality, access and editing paradigms enable the implementation of arbitrary compute
algorithms, such as auto-tracking techniques, which are primarily based on data hosted by the
rendering cluster. In addition, user-defined query methods, such as snapping techniques, or
data export schemes can be implemented efficiently. The general distributed computing concepts
typically rely on a 3D query region (3D bounding box), which an application developer can define
for his purposes.
 
 
Data Locality
=============
The data locality provides the application the information where, i.e., on which machine in the
cluster, the actual data of a distributed dataset is stored. A single cluster machine stores either
none or subsets of the entire data. Furthermore, the data locality information provides the corresponding
3D bounding boxes of each subset. Each of the 3D bounding boxes can be accessed by means of an index
and the respective index also corresponds to a subset.
 
A common use case that requires the data locality is the invocation of parallel and distributed compute tasks.
Based on the data locality, the compute tasks can be directed to the machines that actually store the
distributed data allowing local computation on the data without transferring the data through the network.
 
Distributed Data Access
=======================
The distributed data access queries all data contained in the query bounding box and transfers
them to the calling cluster machine. The queried data is then assembled to form a single subset
of the dataset, i.e., a regular 3D volume. This allows an application developer to inspect or export
on the calling machine. It should be noted that the application developer is responsible to specify
the query bounding box in a practicable and resource-aware way as an entire 3D regular volume dataset
can be enormous (e.g., multiple terabyte) and can easily spill the available local memory.
 
Distributed Data Editing
========================
The distributed data editing paradigm enables distributed editing of the voxel values of a
regular 3D volume dataset. The application can implement an editing or computing task that can be
applied to the each and every brick in the cluster environment. In combination with the data locality,
which allows directing the computation to the machines that store the brick data, the editing paradigm
has become a powerful tool that benefits from the data distribution and enables distributed and parallel
data processing. The today's interfaces not only support the processing of the data in main memory but
also the processing of the data in GPU memory.
 
*/
 
//----------------------------------------------------------------------
class Distributed_heightfield_data:
    public nv::index::app::Index_connect
{
public:
    Distributed_heightfield_data()
        :
        Index_connect()
    {
        // INFO_LOG << "DEBUG: Distributed_heightfield_data() ctor";
    }
 
    virtual ~Distributed_heightfield_data()
    {
        // Note: Index_connect::~Index_connect() will be called after here.
        // INFO_LOG << "DEBUG: ~Distributed_heightfield_data() dtor";
    }
 
    // launch application
    mi::Sint32 launch();
 
protected:
    virtual bool evaluate_options(nv::index::app::String_dict& sdict) CPP11_OVERRIDE;
    // override
    virtual bool initialize_networking(
        mi::neuraylib::INetwork_configuration* network_configuration,
        nv::index::app::String_dict&           options) CPP11_OVERRIDE
    {
        check_success(network_configuration != 0);
 
        check_success(options.is_defined("unittest"));
        const bool is_unittest = nv::index::app::get_bool(options.get("unittest"));
        if (is_unittest)
        {
            info_cout("NETWORK: disabled networking mode.", options);
            network_configuration->set_mode(mi::neuraylib::INetwork_configuration::MODE_OFF);
            return true;
        }
 
        return initialize_networking_as_default_udp(network_configuration, options);
    }
 
private:
    mi::neuraylib::Tag add_synthetic_heightfield(
        const mi::neuraylib::Tag&              session_tag,
        const std::string&                     synthetic_heightfield_type_str,
        const std::string&                     technique_param_str,
        const mi::math::Vector<mi::Uint32, 2>& heightfield_size,
        mi::neuraylib::IDice_transaction*      dice_transaction);
    std::vector<mi::Uint32> evaluate_data_locality(
        const nv::index::IDistributed_data_locality* data_locality,
        const mi::math::Bbox<mi::Uint32, 2>&         query_bound,
        const mi::neuraylib::Tag&                    scene_element_tag,
        const std::string&                           scene_element_type) const;
    // Analyze the data in the heightfield, writing to the log
    // \param[in] heightfield_tag  Tag for the heightfield
    // \param[in] session_tag      Tag for the session
    // \param[in] dice_transaction transaction
    // \return average height
    mi::Float32 analyze_heightfield_data(
        const mi::neuraylib::Tag&         heightfield_tag,
        const mi::neuraylib::Tag&         session_tag,
        mi::neuraylib::IDice_transaction* dice_transaction) const;
    // Edit the data in the heightfield
    void edit_heightfield_data(
        const mi::neuraylib::Tag&         heightfield_tag,
        const mi::neuraylib::Tag&         session_tag,
        mi::neuraylib::IDice_transaction* dice_transaction) const;
    // Render a frame
    // \param[in] output_fname     output rendering image filename
    // \return performance values
    nv::index::IFrame_results* render_frame(const std::string& output_fname) const;
    
    // This session tag
    mi::neuraylib::Tag                                                                m_session_tag;
    // NVIDIA IndeX cluster configuration
    mi::base::Handle<nv::index::ICluster_configuration>                               m_cluster_configuration;
    // Application layer image file canvas (a render target)
    mi::base::Handle<nv::index::app::canvas_infrastructure::IIndex_image_file_canvas> m_image_file_canvas;    
    // Create_icons options
    // std::string                                                                       m_outfname;
    bool                                                                              m_is_unittest;
};
 
//----------------------------------------------------------------------
mi::Sint32 Distributed_heightfield_data::launch()
{
    mi::neuraylib::Tag heightfield_tag;
    {
        m_cluster_configuration =
            get_index_interface()->
            get_api_component<nv::index::ICluster_configuration>();
        check_success(m_cluster_configuration.is_valid_interface());
 
        // create image canvas in application_layer
        m_image_file_canvas = create_image_file_canvas(get_application_layer_interface());
        check_success(m_image_file_canvas.is_valid_interface());
 
        {
            // DiCE database access
            mi::base::Handle<mi::neuraylib::IDice_transaction> dice_transaction(m_global_scope->create_transaction<mi::neuraylib::IDice_transaction>());
            check_success(dice_transaction.is_valid_interface());
            {
                // Setup session information
                m_session_tag = m_index_session->create_session(dice_transaction.get());
                check_success(m_session_tag.is_valid());
                mi::base::Handle<const nv::index::ISession> session(dice_transaction->access<nv::index::ISession>(m_session_tag));
                check_success(session.is_valid_interface());
 
                mi::base::Handle< nv::index::IScene > scene_edit(
                    dice_transaction->edit<nv::index::IScene>(session->get_scene()));
                check_success(scene_edit.is_valid_interface());
 
                // Configuration
                {
                    mi::base::Handle<nv::index::IConfig_settings> edit_config_settings(dice_transaction->edit<nv::index::IConfig_settings>(session->get_config()));
                    check_success(edit_config_settings.is_valid_interface());
 
                    // All data should be uploaded immediately, even when it is not initially visible
                    edit_config_settings->set_force_data_upload(true);
 
                    // Set smaller subcube size in unit test mode (subcube size test)
                    if (m_is_unittest)
                    {
                        const mi::math::Vector<mi::Uint32, 3> subcube_size(30);
                        mi::math::Vector<mi::Float32, 3> minimal_volume_scaling;
                        edit_config_settings->get_minimal_volume_scaling(minimal_volume_scaling);
                        INFO_LOG << "minimal_volume_scaling: " << minimal_volume_scaling
                                 << ", border: " << edit_config_settings->get_subcube_border_size()
                                 << ", rotation support: "
                                 << edit_config_settings->get_volume_rotation_supported();
                        edit_config_settings->set_subcube_configuration(
                            subcube_size,
                            edit_config_settings->get_continuous_volume_translation_supported(),
                            edit_config_settings->get_subcube_border_size(),
                            edit_config_settings->get_volume_rotation_supported(),
                            minimal_volume_scaling);
                    }
                }
 
                //----------------------------------------------------------------------
                // Scene setup: add volume data, scene parameters
                //----------------------------------------------------------------------
 
                // Add a synthetic heightfield to the scene.
                mi::math::Vector<mi::Uint32, 2> heightfield_size(1000, 1000);
                if (m_is_unittest)
                {
                    heightfield_size = mi::math::Vector<mi::Uint32, 2>(100, 100);
                }
                const std::string synthetic_heightfield_type_str = "i"; // synthetic_type
                const std::string technique_param_str = "";
                heightfield_tag = add_synthetic_heightfield(
                    m_session_tag, synthetic_heightfield_type_str, technique_param_str, heightfield_size,
                    dice_transaction.get());
 
                check_success(heightfield_tag.is_valid());
                INFO_LOG << "Created a synthetic regular heightfield: tag = " << heightfield_tag.id;
 
                // Set up the scene
                {
                    // Set region of interest to fit the volume in this example
                    mi::base::Handle<nv::index::IScene> scene(dice_transaction->edit<nv::index::IScene>(session->get_scene()));
                    check_success(scene.is_valid_interface());
 
                    const mi::math::Bbox<mi::Float32, 3> global_region_of_interest(
                        0.0f, 0.0f, 0.0f, 1000.f,1000.f,1000.f);
                    scene->set_clipped_bounding_box(global_region_of_interest);
 
                    // Create a camera
                    mi::base::Handle< nv::index::IPerspective_camera > cam(
                        scene_edit->create_camera<nv::index::IPerspective_camera>());
                    check_success(cam.is_valid_interface());
                    const mi::neuraylib::Tag camera_tag = dice_transaction->store(cam.get());
                    check_success(camera_tag.is_valid());
 
                    scene->set_camera(camera_tag);
                }
                const mi::math::Vector<mi::Uint32, 2> buffer_resolution(1024, 1024);
                m_image_file_canvas->set_resolution(buffer_resolution);
            }
            dice_transaction->commit();
        }
 
        // Rendering
        {
            const std::string fname = ""; // no output file
            render_frame(fname);
        }
 
        // Heightfield analysis
 
        {
            INFO_LOG << "Analyzing heightfield data before editing ...";
            mi::base::Handle<mi::neuraylib::IDice_transaction> dice_transaction(
                m_global_scope->create_transaction<mi::neuraylib::IDice_transaction>());
            check_success(dice_transaction.is_valid_interface());
            mi::Float32 value = analyze_heightfield_data(heightfield_tag, m_session_tag, dice_transaction.get());
            if (m_is_unittest)
            {
                // sum(mod([0:k-1],255))*k/k^2 for 100 = 49.5
                check_success(value == 49.5f);
            }
            else
            {
                // sum(mod([0:k-1],255))*k/k^2 for 1000 = 124.65
                check_success(std::abs(value - 124.287f) < 0.0001f);
            }
            dice_transaction->commit();
        }
 
        // Height field edit
        {
            INFO_LOG << "Editing heightfield data...";
            mi::base::Handle<mi::neuraylib::IDice_transaction> dice_transaction(
                m_global_scope->create_transaction<mi::neuraylib::IDice_transaction>());
            check_success(dice_transaction.is_valid_interface());
            {
                edit_heightfield_data(heightfield_tag, m_session_tag, dice_transaction.get());
            }
            dice_transaction->commit();
        }
 
        // Heightfield re-analysis
        {
            INFO_LOG << "Analyzing heightfield data after editing ...";
            mi::base::Handle<mi::neuraylib::IDice_transaction> dice_transaction(
                m_global_scope->create_transaction<mi::neuraylib::IDice_transaction>());
            check_success(dice_transaction.is_valid_interface());
            mi::Float32 value = analyze_heightfield_data(heightfield_tag, m_session_tag, dice_transaction.get());
            if (m_is_unittest)
            {
                check_success(std::abs(value - 24.75f) < 0.0001f);
            }
            else
            {
                check_success(std::abs(value - 62.1435f) < 0.0001f);
            }
            dice_transaction->commit();
        }
    }
    return 0;
}
 
//----------------------------------------------------------------------
bool Distributed_heightfield_data::evaluate_options(nv::index::app::String_dict& sdict)
{
    const std::string com_name = sdict.get("command:", "<unknown_command>");
    m_is_unittest = nv::index::app::get_bool(sdict.get("unittest", "false"));
    
    if (m_is_unittest)
    {
        if (nv::index::app::get_bool(sdict.get("is_call_from_test", "false")))
        {
            sdict.insert("is_dump_comparison_image_when_failed", "0");
        }
        sdict.insert("dice::verbose", "2");
    }
 
    info_cout(std::string("running ") + com_name, sdict);
 
    // print help and exit if -h
    if (sdict.is_defined("h"))
    {
        std::cout
            << "info: Usage: " << com_name <<" [option]\n"
            << "Option: [-h]\n"
            << "            print this message\n"
            << "        [-dice::network::multicast_address address]\n"
            << "            set multicast address. (default: ["
            << sdict.get("dice::network::multicast_address") + "])\n"
            << "        [-dice::network::cluster_interface]\n"
            << "            set cluster interface. (default: ["
            << sdict.get("dice::network::cluster_interface") + "])\n"
            << std::endl;
        exit(1);
    }
    return true;
}
 
//----------------------------------------------------------------------
mi::neuraylib::Tag Distributed_heightfield_data::add_synthetic_heightfield(
    const mi::neuraylib::Tag&              session_tag,
    const std::string&                     synthetic_heightfield_type_str,
    const std::string&                     technique_param_str,
    const mi::math::Vector<mi::Uint32, 2>& heightfield_size,
    mi::neuraylib::IDice_transaction*      dice_transaction)
{
    check_success(session_tag.is_valid());
    check_success(dice_transaction != 0);
 
    // When a heightfield is created, we need to inform the IndeX library
    // how to create the heightfield. This is a heightfield creation
    // configuration. This configration is also a factory to generate
    // a heightfield generator job.
    nv::index::app::String_dict heightfield_opt;
    heightfield_opt.insert("args::type",           "heightfield");
    heightfield_opt.insert("args::importer",       "nv::index::plugin::legacy_importer.Synthetic_heightfield_generator");
    heightfield_opt.insert("args::synthetic_type", synthetic_heightfield_type_str);
    heightfield_opt.insert("args::parameter",      technique_param_str);
    std::stringstream sstr;
    sstr << heightfield_size.x << " " << heightfield_size.y;
    heightfield_opt.insert("args::size",           sstr.str());
    heightfield_opt.insert("args::range",          "0.1 1000");
    nv::index::IDistributed_data_import_callback* importer_callback =
        get_importer_from_application_layer(
            get_application_layer_interface(),
            "nv::index::plugin::legacy_importer.Synthetic_heightfield_generator",
            heightfield_opt);
 
    mi::base::Handle<nv::index::ISession> session(dice_transaction->edit<nv::index::ISession>(session_tag));
    check_success(session.is_valid_interface());
 
    // Access (edit mode) the scene instance from the database.
    mi::base::Handle<nv::index::IScene> scene_edit(dice_transaction->edit<nv::index::IScene>(session->get_scene()));
    check_success(scene_edit.is_valid_interface());
 
    const std::string                      heightfield_name = "distributed_heightfield_data";
    const mi::math::Vector<mi::Float32, 3> scale(1.0f, 1.0f, 1.0f);
    const mi::Float32                      rotate_k = 0.0f;
    const mi::math::Vector<mi::Float32, 3> translate(1.0f, 1.0f, 1.0f);
 
    // use default range
    const mi::math::Vector<mi::Float32, 2> heightfield_elevation_range(0.0f, 2000.0f);
    mi::base::Handle<nv::index::IRegular_heightfield> heightfield_scene_element(
        scene_edit->create_regular_heightfield(
            scale, rotate_k, translate,
            heightfield_size,
            heightfield_elevation_range,
            importer_callback,
            dice_transaction));
    check_success(heightfield_scene_element.is_valid_interface());
 
    // Set the name of the heightfield
    heightfield_scene_element->set_name(heightfield_name.c_str());
    const mi::neuraylib::Tag heightfield_tag = dice_transaction->store_for_reference_counting(heightfield_scene_element.get());
    check_success(heightfield_tag.is_valid());
    {
        // create static group node for large data and append the volume
        mi::base::Handle<nv::index::IStatic_scene_group> static_group_node(
            scene_edit->create_scene_group<nv::index::IStatic_scene_group>());
        check_success(static_group_node.is_valid_interface());
 
        // Added a light and a material to the static group node
        mi::base::Handle<nv::index::IDirectional_headlight> headlight(scene_edit->create_attribute<nv::index::IDirectional_headlight>());
        check_success(headlight.is_valid_interface());
 
        const mi::math::Color_struct color_intensity = { 1.0f, 1.0f, 1.0f, 1.0f, };
        headlight->set_intensity(color_intensity);
        headlight->set_direction(mi::math::Vector<mi::Float32, 3>(1.0f, -1.0f, -1.0f));
        const mi::neuraylib::Tag headlight_tag = dice_transaction->store_for_reference_counting(headlight.get());
 
        check_success(headlight_tag.is_valid());
        static_group_node->append(headlight_tag, dice_transaction);
 
        // Material for the heightfield
        mi::base::Handle<nv::index::IPhong_gl> phong_1(scene_edit->create_attribute<nv::index::IPhong_gl>());
        check_success(phong_1.is_valid_interface());
 
        const mi::neuraylib::Tag phong_1_tag = dice_transaction->store_for_reference_counting(phong_1.get());
        check_success(phong_1_tag.is_valid());
        static_group_node->append(phong_1_tag, dice_transaction);
 
        // append heightfield to the scene
        static_group_node->append(heightfield_tag, dice_transaction);
        const mi::neuraylib::Tag static_group_node_tag = dice_transaction->store_for_reference_counting(static_group_node.get());
        check_success(static_group_node_tag.is_valid());
 
        // Add the new volume to the hierachical scene description
        scene_edit->append(static_group_node_tag, dice_transaction);
    }
 
    DEBUG_LOG << "Adding the following synthetic heightfield to the scene: " << heightfield_name
              << ", size: "                       << heightfield_size
              << ", scale: "                      << scale
              << ", rotate_k: "                   << rotate_k
              << ", translate: "                  << translate
              << ", (value) range: "              << heightfield_elevation_range;
 
    return heightfield_tag;
}
 
//----------------------------------------------------------------------
std::vector<mi::Uint32> Distributed_heightfield_data::evaluate_data_locality(
    const nv::index::IDistributed_data_locality* data_locality,
    const mi::math::Bbox<mi::Uint32, 2>&         query_bound,
    const mi::neuraylib::Tag&                    scene_element_tag,
    const std::string&                           scene_element_type) const
{
    // Determine all host in the cluster that store part of the distributed data (here: regular volume).
    std::vector<mi::Uint32> cluster_host_ids;
    std::ostringstream hosts;
    std::ostringstream locality_report;
    for (mi::Uint32 i=0; i < data_locality->get_nb_cluster_nodes(); ++i)
    {
        // A host id=0 indicates that an issue occurred, e.g., no data has been loaded or no distribution scheme has been set up.
        check_success(data_locality->get_cluster_node(i) != 0);
 
        const mi::Uint32 host_id = data_locality->get_cluster_node(i);
        cluster_host_ids.push_back(host_id);
 
        // The remaining part is just for reporting/logging.
        hosts << host_id << " ";
 
        const mi::Size nb_subregions = data_locality->get_nb_bounding_box(host_id);
        locality_report << "Host " << host_id << " stores part of the distributed data in the following " << nb_subregions << " regions:\n";
        for (mi::Uint32 j=0; j<nb_subregions; ++j)
        {
            const mi::math::Bbox<mi::Sint32, 3> bbox = data_locality->get_bounding_box(host_id, j);
            locality_report << "  " << (j+1) << ")\t" << bbox;
            if (j < nb_subregions - 1)
            {
                locality_report << "\n";
            }
        }
    }
    INFO_LOG << "\n"
             << "Data locality for a " << scene_element_type
             << " with tag id " << scene_element_tag.id
             << " and query region " << query_bound << "\n:"
             << "The distributed data is located on the following hosts (ids): [ " << hosts.str() << "]." << "\n"
             << locality_report.str()
             << "\n";
 
    return cluster_host_ids;
}
 
//----------------------------------------------------------------------
mi::Float32 Distributed_heightfield_data::analyze_heightfield_data(
    const mi::neuraylib::Tag&         heightfield_tag,
    const mi::neuraylib::Tag&         session_tag,
    mi::neuraylib::IDice_transaction* dice_transaction) const
{
    mi::base::Handle<const nv::index::ISession> the_session(dice_transaction->access<nv::index::ISession>(session_tag));
    check_success(the_session.is_valid_interface());
 
    mi::base::Handle<const nv::index::IRegular_heightfield> heightfield(
        dice_transaction->access<nv::index::IRegular_heightfield>(heightfield_tag));
    check_success(heightfield.is_valid_interface());
 
    const mi::math::Bbox<mi::Float32, 3> heightfield_bbox = heightfield->get_IJK_bounding_box();
 
    const mi::math::Bbox<mi::Uint32, 2> query_bbox(
        static_cast<mi::Uint32>(heightfield_bbox.min.x), static_cast<mi::Uint32>(heightfield_bbox.min.y),
        static_cast<mi::Uint32>(heightfield_bbox.max.x), static_cast<mi::Uint32>(heightfield_bbox.max.y));
 
    // Access the distribution scheme
    const mi::neuraylib::Tag dist_layout_tag = the_session->get_distribution_layout();
    check_success(dist_layout_tag.is_valid());
 
    mi::base::Handle<const nv::index::IData_distribution> distribution_layout(
        dice_transaction->access<nv::index::IData_distribution>(dist_layout_tag));
    check_success(distribution_layout.is_valid_interface());
 
    // Find out on which hosts the data is located and print this information
    mi::base::Handle<nv::index::Regular_heightfield_locality_query_mode> mode(
        new nv::index::Regular_heightfield_locality_query_mode(heightfield_tag, query_bbox, false));
    mi::base::Handle<nv::index::IDistributed_data_locality> data_locality(
        distribution_layout->get_data_locality<nv::index::IRegular_heightfield>(mode.get(), dice_transaction));
 
    // Determine all host in the cluster that store part of the distributed data (here: heightfield).
    std::vector<mi::Uint32> cluster_host_ids = evaluate_data_locality(
        data_locality.get(), query_bbox, heightfield_tag, heightfield->get_class_name());
 
    // Create the access factory
    const mi::neuraylib::Tag data_access_tag = the_session->get_data_access_factory();
    check_success(data_access_tag.is_valid());
 
    mi::base::Handle<const nv::index::IDistributed_data_access_factory> access_factory(
        dice_transaction->access<nv::index::IDistributed_data_access_factory>(data_access_tag));
    check_success(access_factory.is_valid_interface());
 
    mi::base::Handle<nv::index::IRegular_heightfield_data_access> data_access(
        access_factory->create_regular_heightfield_data_access(heightfield_tag));
    check_success(data_access.is_valid_interface());
 
    // Now retrieve the data
    data_access->access(query_bbox, dice_transaction);
 
    const mi::math::Bbox<mi::Uint32, 2> effective_bbox = data_access->get_patch_bounding_box();
    INFO_LOG << effective_bbox;
    INFO_LOG << query_bbox;
 
    // Average the contents of the trace
    const mi::Float32* height_data = data_access->get_elevation_values();
 
    mi::Sint64 count = effective_bbox.volume();
    mi::Float32 height_sum = 0;
    mi::Float32 height_min = std::numeric_limits<mi::Float32>::max();
    mi::Float32 height_max = std::numeric_limits<mi::Float32>::min();
 
    for (mi::Sint64 k = 0; k < count; ++k)
    {
        mi::Float32 height = height_data[k];
        height_sum += height;
 
        if (height > height_max)
        {
            height_max = height;
        }
        if (height < height_min)
        {
            height_min = height;
        }
    }
 
    mi::Float32 avg = static_cast<mi::Float32>(height_sum) / static_cast<mi::Float32>(count);
    INFO_LOG << "Heightfield height: "
             << "count=" << count
             << ", min=" << height_min
             << ", max=" << height_max
             << ", avg=" << avg;
 
    return avg;
}
 
//----------------------------------------------------------------------
void Distributed_heightfield_data::edit_heightfield_data(
    const mi::neuraylib::Tag&         heightfield_tag,
    const mi::neuraylib::Tag&         session_tag,
    mi::neuraylib::IDice_transaction* dice_transaction) const
{
    mi::base::Handle<const nv::index::ISession> the_session(dice_transaction->access<nv::index::ISession>(session_tag));
    check_success(the_session.is_valid_interface());
 
    mi::base::Handle<const nv::index::IRegular_heightfield> heightfield(dice_transaction->access<nv::index::IRegular_heightfield>(heightfield_tag));
    check_success(heightfield.is_valid_interface());
 
    const mi::math::Bbox<mi::Float32, 3> heightfield_bbox = heightfield->get_IJK_bounding_box();
 
    const mi::math::Bbox<mi::Uint32, 2> query_bbox(
        static_cast<mi::Uint32>(heightfield_bbox.min.x), static_cast<mi::Uint32>(heightfield_bbox.min.y),
        static_cast<mi::Uint32>(heightfield_bbox.max.x), static_cast<mi::Uint32>(heightfield_bbox.max.y));
 
    // Access the data distribution scheme that exposes the locality of the distribution data (here: heightfield).
    const mi::neuraylib::Tag dist_layout_tag = the_session->get_distribution_layout();
    check_success(dist_layout_tag.is_valid());
    mi::base::Handle<const nv::index::IData_distribution> distribution_layout(dice_transaction->access<nv::index::IData_distribution>(dist_layout_tag));
    check_success(distribution_layout.is_valid_interface());
 
    // Distribution layout
    mi::base::Handle<nv::index::Regular_heightfield_locality_query_mode> mode(
        new nv::index::Regular_heightfield_locality_query_mode(heightfield_tag, query_bbox, false));
    mi::base::Handle<nv::index::IDistributed_data_locality> data_locality(
        distribution_layout->get_data_locality<nv::index::IRegular_heightfield>(mode.get(), dice_transaction));
 
    // Determine all host in the cluster that store part of the distributed data (here: heightfield).
    std::vector<mi::Uint32> cluster_host_ids = evaluate_data_locality(
        data_locality.get(),
        query_bbox,
        heightfield_tag,
        heightfield->get_class_name());
 
    // Set up distributed compute algorithm and start the job.
    const bool do_scaling = true;
    const mi::Float32 scale_factor = 0.5f;
    INFO_LOG << "-----------------Scaling the height field's elevation values using the following scale factor: " << scale_factor << "... ";
 
    std::vector<mi::math::Vector_struct<mi::Float32, 2> > region;
    region.push_back(mi::math::Vector<mi::Float32, 2>(heightfield_bbox.min.x, heightfield_bbox.min.y));
    region.push_back(mi::math::Vector<mi::Float32, 2>(heightfield_bbox.min.x, heightfield_bbox.max.y));
    region.push_back(mi::math::Vector<mi::Float32, 2>(heightfield_bbox.max.x, heightfield_bbox.max.y));
    region.push_back(mi::math::Vector<mi::Float32, 2>(heightfield_bbox.max.x, heightfield_bbox.min.y));
 
 
    // Access an application layer component that provides some sample jobs such as the heightfield elevation editing job:
    mi::base::Handle<nv::index::app::data_analysis_and_processing::IData_analysis_and_processing> processing(
    get_application_layer_interface()->get_api_component<nv::index::app::data_analysis_and_processing::IData_analysis_and_processing>());
    check_success(processing.is_valid_interface());
 
    // Create a distributed data job and schedule to run again the height field data. For more details on how to implement the such a job,
    // please review the provided source that was shipped with the application layer component 'nv::index::app::data_analysis_and_processing::IData_analysis_and_processing'.
    mi::base::Handle<nv::index::IDistributed_data_job> distributed_job(
        processing->get_sample_tool_set()->create_heightfield_elevation_editing(
            heightfield_tag, do_scaling, scale_factor, &region.at(0), 4));
    check_success(distributed_job.is_valid_interface());
 
    distribution_layout->create_scheduler()->execute(distributed_job.get(), dice_transaction);
}
 
//----------------------------------------------------------------------
nv::index::IFrame_results* Distributed_heightfield_data::render_frame(const std::string& output_fname) const
{
    check_success(m_index_rendering.is_valid_interface());
 
    // set output filename, empty string is valid
    m_image_file_canvas->set_rgba_file_name(output_fname.c_str());
 
    check_success(m_session_tag.is_valid());
 
    mi::base::Handle<mi::neuraylib::IDice_transaction> dice_transaction(
        m_global_scope->create_transaction<mi::neuraylib::IDice_transaction>());
    check_success(dice_transaction.is_valid_interface());
 
    m_index_session->update(m_session_tag, dice_transaction.get());
 
    mi::base::Handle<nv::index::IFrame_results> frame_results(
        m_index_rendering->render(
            m_session_tag,
            m_image_file_canvas.get(),
            dice_transaction.get()));
    check_success(frame_results.is_valid_interface());
 
    dice_transaction->commit();
 
    frame_results->retain();
    return frame_results.get();
}
 
//----------------------------------------------------------------------
// The API example illustrates the use of the general distributed computing concepts
// data locality, access and edit applied to a sysnthetic heightfield dataset.
//
int main(int argc, const char* argv[])
{
    nv::index::app::String_dict sdict;
    sdict.insert("dice::verbose", "3");                            // log level
    sdict.insert("unittest", "0");                                 // default mode
    sdict.insert("dice::network::multicast_address", "224.1.3.2"); // default multicast address
    sdict.insert("dice::network::cluster_interface", "");          // default cluster interface address
    sdict.insert("is_dump_comparison_image_when_failed", "1");     // default: dump images when failed.
    sdict.insert("is_call_from_test", "0");                        // default: not call from make check.
 
    // Load IndeX library via Index_connect
    sdict.insert("dice::network::mode", "OFF");
 
    // index setting
    sdict.insert("index::config::set_monitor_performance_values", "true");
    sdict.insert("index::service", "rendering_and_compositing");
    sdict.insert("index::cuda_debug_checks", "false");
 
    // application_layer component loading
    sdict.insert("index::app::components::application_layer::component_name_list",
                 "canvas_infrastructure image io data_analysis_and_processing");
    sdict.insert("index::app::plugins::base_importer::enabled", "true");
    sdict.insert("index::app::plugins::legacy_importer::enabled", "true");
 
    // Initialize application
    Distributed_heightfield_data distributed_heightfield_data;
    distributed_heightfield_data.initialize(argc, argv, sdict);
    check_success(distributed_heightfield_data.is_initialized());
 
    // launch the application. creating the scene and rendering.
    const mi::Sint32 exit_code = distributed_heightfield_data.launch();
    INFO_LOG << "Shutting down ...";
 
    return exit_code;
}