feat: Space Ranger 3.1.1

Author: 10x Genomics

Cargo.lock

@@ -0,0 +1,5 @@
+[workspace]
+members = [
+    "fiducial",
+    "image-transform"
+]

Cargo.toml

@@ -0,0 +1,15 @@
+Copyright (c) 2023 10x Genomics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to use, copy, modify, and/or merge copies of the Software, in both source code and object code format, solely for your internal use, subject to the following conditions:
+
+1. The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+2. The above rights granted in the Software may be exercised only in connection with a 10x Genomics Product (defined below), rightfully purchased from 10x Genomics or an authorized reseller, or data generated using such a 10x Genomics Product. A “10X Genomics Product” means, collectively, 10x Genomics branded instruments, reagents, consumables, kits, and labware used in accordance with the 10X Genomics Product Terms and Conditions of Sale or, if applicable, any written contract between you and 10x Genomics. The rights granted may also be exercised in connection with other products when doing so is an integral part of an experiment where the data is generated primarily using a 10x Genomics Product.
+
+3. You agree not to redistribute or sublicense the Software, either in source code or object code format.
+
+4. All derivative works, including any modifications of the Software, shall be subject to all of the restrictions set forth herein.
+
+5. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE, THE USE OR INABILITY TO USE, OR OTHER DEALINGS IN THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+You may not use, propagate or modify the Software, or any derivatives thereof, except as expressly provided herein. Any attempt otherwise to use, propagate or modify it is void, and will automatically terminate your rights under this license.

LICENSE.txt

@@ -0,0 +1,12 @@
+# Image Analysis
+
+[![Test](https://github.com/10XDev/rust-template/actions/workflows/test.yaml/badge.svg)](https://github.com/10XDev/rust-template/actions/workflows/test.yaml)
+
+This repository holds rust implementations of image analysis algorithms used in Spaceranger.
+Currently, this includes implementations of Visium HD fiducial detection and basic image transformations.
+
+## Fiducial Detection and Registration
+Fiducial code for Visium HD. Contains the fiducial detection, decoding and registration algorithms used in Spaceranger.
+An outline of the fiducial detection algorithm is described [here][]. 
+
+[here]: https://www.cv-foundation.org/openaccess/content_cvpr_2016/papers/Calvet_Detection_and_Accurate_CVPR_2016_paper.pdf

README.md

@@ -0,0 +1,175 @@
+# If 1 or more target triples (and optionally, target_features) are specified,
+# only the specified targets will be checked when running `cargo deny check`.
+# This means, if a particular package is only ever used as a target specific
+# dependency, such as, for example, the `nix` crate only being used via the
+# `target_family = "unix"` configuration, that only having windows targets in
+# this list would mean the nix crate, as well as any of its exclusive
+# dependencies not shared by any other crates, would be ignored, as the target
+# list here is effectively saying which targets you are building for.
+targets = [
+    { triple = "x86_64-unknown-linux-gnu" },
+]
+
+# This section is considered when running `cargo deny check advisories`
+# More documentation for the advisories section can be found here:
+# https://embarkstudios.github.io/cargo-deny/checks/advisories/cfg.html
+[advisories]
+# The path where the advisory database is cloned/fetched into
+# db-path = "~/.cargo/advisory-db"
+# The url(s) of the advisory databases to use
+db-urls = ["https://github.com/rustsec/advisory-db"]
+# The lint level for security vulnerabilities
+vulnerability = "deny"
+# The lint level for unmaintained crates
+unmaintained = "warn"
+# The lint level for crates that have been yanked from their source registry
+yanked = "warn"
+# The lint level for crates with security notices. Note that as of
+# 2019-12-17 there are no security notice advisories in
+# https://github.com/rustsec/advisory-db
+notice = "warn"
+# A list of advisory IDs to ignore. Note that ignored advisories will still
+# output a note when they are encountered.
+ignore = [
+]
+
+# This section is considered when running `cargo deny check licenses`
+# More documentation for the licenses section can be found here:
+# https://embarkstudios.github.io/cargo-deny/checks/licenses/cfg.html
+[licenses]
+# The lint level for crates which do not have a detectable license
+unlicensed = "deny"
+# Allow us to keep a consistent list across projects without needing
+# to customize deny.toml based on what's actually present.
+unused-allowed-license = "allow"
+# List of explictly allowed licenses
+# See https://spdx.org/licenses/ for list of possible licenses
+# [possible values: any SPDX 3.11 short identifier (+ optional exception)].
+allow = [
+    "0BSD",
+    "Apache-2.0",
+    "Apache-2.0 WITH LLVM-exception",
+    "BSD-2-Clause",
+    "BSD-3-Clause",
+    "ISC",
+    "MIT",
+    "MIT-0",
+    "MPL-2.0",
+    "OpenSSL",
+    "Unicode-DFS-2016",
+    "WTFPL",
+]
+# List of explictly disallowed licenses
+# See https://spdx.org/licenses/ for list of possible licenses
+# [possible values: any SPDX 3.11 short identifier (+ optional exception)].
+deny = [
+    #"Nokia",
+]
+# Lint level for licenses considered copyleft
+copyleft = "deny"
+# Blanket approval or denial for OSI-approved or FSF Free/Libre licenses
+# * both - The license will be approved if it is both OSI-approved *AND* FSF
+# * either - The license will be approved if it is either OSI-approved *OR* FSF
+# * osi-only - The license will be approved if is OSI-approved *AND NOT* FSF
+# * fsf-only - The license will be approved if is FSF *AND NOT* OSI-approved
+# * neither - This predicate is ignored and the default lint level is used
+allow-osi-fsf-free = "neither"
+# Lint level used when no other predicates are matched
+# 1. License isn't in the allow or deny lists
+# 2. License isn't copyleft
+# 3. License isn't OSI/FSF, or allow-osi-fsf-free = "neither"
+default = "deny"
+# The confidence threshold for detecting a license from license text.
+# The higher the value, the more closely the license text must be to the
+# canonical license text of a valid SPDX license file.
+# [possible values: any between 0.0 and 1.0].
+confidence-threshold = 0.6
+
+[licenses.private]
+# If true, ignores workspace crates that aren't published, or are only
+# published to private registries
+ignore = true
+# One or more private registries that you might publish crates to, if a crate
+# is only published to private registries, and ignore is true, the crate will
+# not have its license(s) checked
+registries = [
+    #"https://sekretz.com/registry
+]
+
+[[licenses.exceptions]]
+name = "intel-mkl-src"
+allow = ["LicenseRef-Intel-SmpL"]
+
+# Some crates don't have (easily) machine readable licensing information,
+# adding a clarification entry for it allows you to manually specify the
+# licensing information
+[[licenses.clarify]]
+name = "intel-mkl-src"
+expression = "LicenseRef-Intel-SmpL"
+
+[[licenses.clarify.license-files]]
+path = "../License.txt"
+hash = 0x3bf8c2d0
+
+# This section is considered when running `cargo deny check bans`.
+# More documentation about the 'bans' section can be found here:
+# https://embarkstudios.github.io/cargo-deny/checks/bans/cfg.html
+[bans]
+# Lint level for when multiple versions of the same crate are detected
+multiple-versions = "deny"
+# Lint level for when a crate version requirement is `*`
+wildcards = "allow"
+# The graph highlighting used when creating dotgraphs for crates
+# with multiple versions
+# * lowest-version - The path to the lowest versioned duplicate is highlighted
+# * simplest-path - The path to the version with the fewest edges is highlighted
+# * all - Both lowest-version and simplest-path are used
+highlight = "all"
+# List of crates that are allowed. Use with care!
+
+[[bans.skip]]
+# so many things still on syn 1
+name = "syn"
+version = "1.0.109"
+
+[[bans.skip]]
+# remove after updating ndarray-stats
+name = "indexmap"
+version = "1.9.3"
+
+[[bans.skip]]
+# remove after updating ndarray-stats
+name = "hashbrown"
+version = "0.12.3"
+
+[[bans.skip]]
+# remove after updating ndarray
+name = "approx"
+version = "0.4.0"
+
+[[bans.skip]]
+# remove after updating ndarray-stats
+name = "itertools"
+version = "0.10.5"
+
+[[bans.skip]]
+name = "bitflags"
+version = "1.3.2"
+
+# This section is considered when running `cargo deny check sources`.
+# More documentation about the 'sources' section can be found here:
+# https://embarkstudios.github.io/cargo-deny/checks/sources/cfg.html
+[sources]
+# Lint level for what to happen when a crate from a crate registry that is not
+# in the allow list is encountered
+unknown-registry = "deny"
+# Lint level for what to happen when a crate from a git repository that is not
+# in the allow list is encountered
+unknown-git = "deny"
+# List of URLs for allowed crate registries. Defaults to the crates.io index
+# if not specified. If it is specified but empty, no registries are allowed.
+allow-registry = ["https://github.com/rust-lang/crates.io-index"]
+
+[sources.allow-org]
+# 1 or more github.com organizations to allow git sources for
+github = ["10XGenomics"]

deny.toml

@@ -0,0 +1,37 @@
+[package]
+name = "fiducial"
+version = "0.1.0"
+authors = ["Chaitanya Aluru <chaitanya.aluru@10xgenomics.com>"]
+edition = "2018"
+license = "LicRef-10XGenomics"
+license-file = "../LICENSE.txt"
+include = ["src/**/*.rs", "Cargo.toml"]
+publish = false
+
+[lib]
+name = "fiducial"
+
+[dependencies]
+image = { version = "0.25", default-features = false, features = ["tiff"] }
+itertools = ">=0.10.0"
+kd-tree = "0.6.0"
+ndarray = { version = "0.15.3", features = ["approx", "blas", "serde-1"] }
+ndarray-npy = { version = "*", default-features = false }
+ndarray-linalg = "0.16.0"
+assert_approx_eq = "1.1.0"
+ndarray-stats = "0.5.0"
+rand = "0.8.4"
+slog = "2.7.0"
+slog-term = "2"
+slog-async = "2.7.0"
+
+[dev-dependencies]
+clap = {version = "4.5.16", features = ["derive"]}
+
+[target.'cfg(target_os = "macos")'.dependencies]
+accelerate-src = "0.3.2"
+
+[target.'cfg(not(target_os = "macos"))'.dependencies]
+intel-mkl-src = { git = "https://github.com/10XGenomics/intel-mkl-src", branch = "master", features = [
+    "mkl-static-lp64-seq",
+] }

fiducial/Cargo.toml

@@ -0,0 +1,31 @@
+//Perform Fiducial Detection and Decoding on an input image
+
+use clap::Parser;
+use fiducial::{
+    fiducial_detector::{detect_fiducial, FidDetectionParameter},
+    utils::ImageUtil,
+};
+
+#[derive(Parser)]
+#[command(version, about, long_about = None)]
+struct Args {
+    //path to RGB TIFF file
+    #[arg(short, long)]
+    image_path: String,
+}
+
+fn main() {
+    //read input image
+    let args = Args::parse();
+    let full_image = ImageUtil::read_r_channel(&args.image_path);
+    let param = FidDetectionParameter::new_visium_hd_param();
+    let (detected_names, detected_centers): (Vec<_>, Vec<_>) =
+        detect_fiducial(&full_image, &param, &None)
+            .iter()
+            .cloned()
+            .unzip();
+    detected_names
+        .iter()
+        .zip(detected_centers)
+        .for_each(|(name, center)| println!("{}: {:?}", name, center));
+}

fiducial/examples/fiducial_detection.rs

@@ -0,0 +1,68 @@
+//Perform fiducial detection and registration between an input image and
+//the Visium HD design
+
+use std::{
+    fs::File,
+    io::{BufRead, BufReader},
+};
+
+use clap::Parser;
+use fiducial::utils::ImageUtil;
+use fiducial::{
+    fiducial_detector::{detect_fiducial, FidDetectionParameter},
+    fiducial_registration::{
+        fiducial_refinement_and_perspective_transform_isolation, fiducial_registration, Coord,
+        FiducialFrame, FiducialPoint,
+    },
+};
+
+#[derive(Parser)]
+#[command(version, about, long_about = None)]
+struct Args {
+    //path to RGB TIFF file
+    #[arg(short, long)]
+    image_path: String,
+}
+
+fn main() {
+    //read design
+    let path = "testing_data/design.txt";
+    let file = File::open(path).expect("could not read design file");
+    let buf = BufReader::new(file);
+    let temp: Vec<FiducialPoint> = buf.lines().map(|x| x.unwrap().parse().unwrap()).collect();
+    let mut design = FiducialFrame::new(temp);
+
+    //run fiducial detection
+    let args = Args::parse();
+    let full_image = ImageUtil::read_r_channel(&args.image_path);
+    let param = FidDetectionParameter::new_visium_hd_param();
+    let (detected_names, detected_centers): (Vec<_>, Vec<_>) =
+        detect_fiducial(&full_image, &param, &None)
+            .iter()
+            .cloned()
+            .unzip();
+
+    let detected_centers: Vec<_> = detected_centers
+        .iter()
+        .map(|x| Coord(x[0] as f64, x[1] as f64))
+        .collect();
+    let mut detected_frame = FiducialFrame::from_points(&detected_names, &detected_centers);
+
+    let homography = fiducial_registration(&mut detected_frame, &mut design)
+        .expect("could not compute homography")
+        .0;
+
+    println!("Computed Homography:\n{:?}", homography);
+
+    let refinement_with_perspective_transform =
+        fiducial_refinement_and_perspective_transform_isolation(
+            &args.image_path,
+            &homography,
+            &mut design,
+        )
+        .unwrap();
+    println!(
+        "Refinement with perspective transform isolation output:\n{:?}\n{:?}",
+        refinement_with_perspective_transform.0, refinement_with_perspective_transform.1
+    );
+}