MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
RegionKeySorter.hpp
Go to the documentation of this file.
1#pragma once
2
4#include "BitonicSorter.hpp"
5#include "Sorter.hpp"
6
7/**
8 * @file RegionKeySorter.hpp
9 * @brief Orders region groups by a weighted score of their feature facets.
10 */
11
12namespace MayaFlux::Yantra {
13
14/**
15 * @struct RegionKeySorterConfig
16 * @brief Settings of RegionKeySorter, stored whole in the operation's facets.
17 *
18 * The keys are the terms of the score. The GPU threshold selects the dispatch path.
19 */
21 /** Terms of the weighted sort score. Weights are validated on construction. */
22 std::vector<SortKey> keys;
23
24 /** Region count at or above which the GPU path is used. 0 keeps the sort on the CPU. */
25 uint32_t gpu_sort_threshold { 0 };
26};
27
28MF_DESCRIBE(RegionKeySorterConfig)
29
30/**
31 * @class RegionKeySorter
32 * @brief Orders regions by their weighted sort score.
33 *
34 * Each region's score is weighted_sort_score over the configured keys. Regions
35 * are ordered by ascending score. A DESCENDING key negates its term, so
36 * direction lives in the keys. Empty keys leave the group unchanged. A region
37 * that lacks any key's feature is a hard error.
38 *
39 * The GPU path orders the scores with BitonicSorter over order keys. It returns
40 * the same permutation as the CPU path: ascending, with equal scores in input
41 * order and NaN last.
42 */
43class RegionKeySorter : public Sorter<Kakshya::RegionGroup, Kakshya::RegionGroup> {
44public:
46
47 /**
48 * @brief Construct a region key sorter from its settings.
49 * @param config Keys and GPU threshold. Key weights are validated.
50 */
52 {
53 validate_sort_keys(config.keys);
54 set_config(std::move(config));
55 }
56
57 /**
58 * @brief The stored settings, or defaults when none were set.
59 */
60 [[nodiscard]] ConfigRefs configs() const override
61 {
62 return stored_configs(supports {});
63 }
64
65 [[nodiscard]] SortingType get_sorting_type() const override
66 {
68 }
69
70protected:
71 Datum<Kakshya::RegionGroup> sort_implementation(
72 const Datum<Kakshya::RegionGroup>& input) override;
73
74private:
75 /**
76 * @brief Ascending order of the scores, computed exactly on the GPU.
77 */
78 static std::vector<size_t> gpu_order(const std::vector<double>& scores);
79};
80
82 const Datum<Kakshya::RegionGroup>& input)
83{
84 const auto& cfg = config<RegionKeySorterConfig>();
86 const auto n = out.data.regions.size();
87
88 if (n == 0 || cfg.keys.empty()) {
89 return out;
90 }
91
92 std::vector<double> scores(n);
93 for (size_t i = 0; i < n; ++i) {
94 const auto score = weighted_sort_score(out.data.regions[i], cfg.keys);
95 if (!score) {
96 error<std::runtime_error>(Journal::Component::Yantra, Journal::Context::ComputeMatrix, std::source_location::current(), "RegionKeySorter: a region lacks a sort key feature");
97 }
98 scores[i] = *score;
99 }
100
101 std::vector<size_t> order(n);
102 if (cfg.gpu_sort_threshold > 0 && n >= cfg.gpu_sort_threshold) {
103 order = gpu_order(scores);
104 } else {
105 std::iota(order.begin(), order.end(), size_t { 0 });
106 std::ranges::stable_sort(order, [&](size_t a, size_t b) { return scores[a] < scores[b]; });
107 }
108
109 std::vector<Kakshya::Region> reordered;
110 reordered.reserve(n);
111 for (size_t idx : order) {
112 reordered.push_back(out.data.regions[idx]);
113 }
114 out.data.regions = std::move(reordered);
115 out.data.current_region_index = 0;
116 out.data.active_indices.clear();
117 return out;
118}
119
120inline std::vector<size_t> RegionKeySorter::gpu_order(const std::vector<double>& scores)
121{
123 config.direction = SortingDirection::ASCENDING;
124 BitonicSorter<> sorter(config);
125 return sorter.order(scores);
126}
127
128} // namespace MayaFlux::Yantra
Exact GPU sorting of numeric channels by a bitonic network over order keys.
#define MF_DESCRIBE(...)
Requests a generated member description for a struct at namespace scope.
Definition Describe.hpp:14
Modern, digital-first sorting framework for Maya Flux.
std::vector< size_t > order(std::span< const double > values)
The indices that order one channel, computed on the GPU in the configured direction.
Sorts each numeric channel on the GPU, exactly, without fp64.
ConfigRefs stored_configs(Supports< Configs... >) const
RegionKeySorter(RegionKeySorterConfig config={})
Construct a region key sorter from its settings.
static std::vector< size_t > gpu_order(const std::vector< double > &scores)
Ascending order of the scores, computed exactly on the GPU.
Datum< Kakshya::RegionGroup > sort_implementation(const Datum< Kakshya::RegionGroup > &input) override
ConfigRefs configs() const override
The stored settings, or defaults when none were set.
Supports< RegionKeySorterConfig > supports
SortingType get_sorting_type() const override
Gets the sorting type category for this sorter.
Template-flexible sorter base with instance-defined I/O types.
Definition Sorter.hpp:106
@ ComputeMatrix
Compute operations (Yantra - algorithms, matrices, DSP).
@ Yantra
DSP algorithms, computational units, matrix operations, Grammar.
SortingType
Categories of sorting operations for discovery and organization.
Definition Sorter.hpp:55
@ ALGORITHMIC
Mathematical/computational sorting algorithms.
Definition Sorter.hpp:57
void validate_sort_keys(const std::vector< SortKey > &keys)
Checks that every sort key has a positive, finite weight.
std::vector< std::reference_wrapper< const OperationConfig > > ConfigRefs
Borrowed views of the configs an operation holds.
std::optional< double > weighted_sort_score(const Element &element, std::span< const SortKey > keys)
Weighted score of one element across the sort keys.
T data
The actual computation data.
Definition DataIO.hpp:64
Input/Output container for computation pipeline data flow with structure preservation.
Definition DataIO.hpp:63
std::vector< SortKey > keys
Terms of the weighted sort score.
uint32_t gpu_sort_threshold
Region count at or above which the GPU path is used.
Settings of RegionKeySorter, stored whole in the operation's facets.
Parent of every sorter's config struct.
Definition Sorter.hpp:88
Settings for standard sorting.
The config structs an operation class accepts, declared as using supports.