Jungfraujoch/image_analysis/scale_merge/SublatticeRelabel.h

// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute <filip.leonarski@psi.ch>
// SPDX-License-Identifier: GPL-3.0-only

#pragma once

#include <array>
#include <optional>
#include <vector>

#include "../../common/CrystalLattice.h"
#include "../../common/IndexingSettings.h"
#include "../../common/UnitCell.h"
#include "../IntegrationOutcome.h"

// A still indexed on few spots is often given a lattice that explains them just as well as the true
// one: an axis multiple (a supercell, whose reciprocal lattice holds every true node plus nodes in
// between) or the true lattice in another setting. Such a frame's cell is not close to the run's cell,
// so the merge leaves it out, although its reflections at the true nodes are as good as any.
//
// FindSublatticeBases looks for the run's reciprocal lattice inside the frame's: integer combinations
// of the frame's reciprocal axes whose metric (all three lengths and three angles) is the reference
// cell's, within the merge's own cell tolerances. Each is returned as the integer matrix M with
// (a*, b*, c*)_reference = M (a*, b*, c*)_frame, right-handed.
std::vector<std::array<std::array<int, 3>, 3>> FindSublatticeBases(const CrystalLattice &frame,
                                                                   const UnitCell &reference,
                                                                   const IndexingSettings &settings);

// A frame's cell described on the reference's axes, when its lattice contains the reference (the
// reference in another setting, or an axis multiple of it): the cell the frame has once it is put on the
// reference. Empty where the lattice does not contain it.
std::optional<UnitCell> CellOnReference(const UnitCell &cell, const UnitCell &reference,
                                        const IndexingSettings &settings);

struct SublatticeRelabelResult {
    size_t frames = 0;            // frames put on the reference cell
    size_t reflections_kept = 0;  // reflections of those frames at nodes of the reference lattice
    size_t reflections_dropped = 0;
};

// For every frame whose cell is not close to the reference but whose lattice contains it: re-derive its
// reflection indices on the reference axes - of several ways to place the reference in its lattice, the
// one with the strongest mean I/sigma at its nodes - drop the reflections that are not reference nodes
// or are finer than any frame on the reference cell reaches, and give the frame the reference basis in
// its own orientation.
SublatticeRelabelResult RelabelOnSublattice(std::vector<IntegrationOutcome> &outcomes,
                                            const UnitCell &reference,
                                            const IndexingSettings &settings);