Uchimata: 3D Genome Visualization Toolkit

• Uchimata is a toolkit for interactive 3D genome visualization that offers a clear, dual-mode deployment in web and Jupyter environments.
• It employs a dual-component design with a JavaScript library for browser rendering and a Python widget for seamless integration in computational workflows.
• Its high-level API supports declarative visual encoding, filtering based on genomic semantics and spatial properties, and interoperability with established data structures.

Searching arXiv for papers relevant to “Uchimata” to ground the article in current literature. arXiv_search(query="Uchimata OR \"Uchi-mata\" OR \"3D genome visualization\" toolkit", max_results=10) Uchimata is a toolkit for visualization of 3D structures of genomes, released as a JavaScript library for rendering on the web and as a Python widget for visualization in Jupyter Notebooks. It is positioned as infrastructure for a gap in the 3D genomics ecosystem: researchers can generate or obtain 3D genome models, but flexible, reusable, notebook-friendly visualization tools that are easy to integrate into analysis workflows have been limited. Its central technical contribution is a high-level API with genomic context, including an expressive way to specify visual encodings and filtering of 3D genome structures based on genomic semantics and spatial aspects (Kouřil et al., 16 Sep 2025).

1. Scope, problem setting, and intended audience

Uchimata addresses interactive visualization of 3D genome structures in two settings: on the web via a JavaScript library and inside computational notebooks via a Python/Jupyter widget. The paper frames this as a response to several ecosystem-level constraints. Existing 3D genome viewers are often standalone desktop or web applications, are difficult to customize, are hard to embed in larger systems, and are not well aligned with Python-based computational biology workflows. Notebook-based workflows are described as standard in computational biology, yet native support for 3D genome visualization in notebooks has lagged behind (Kouřil et al., 16 Sep 2025).

The intended audience is correspondingly broad within computational genomics and scientific software engineering. The toolkit is presented as relevant to computational biologists analyzing or simulating 3D genome structures, bioinformatics developers building genome browsers or data portals, and notebook users in Jupyter or JavaScript notebook environments who require direct interactive 3D visualization during analysis. It is also designed for cases in which custom visual encodings, selection and filtering, and integration with genomic data analysis tools are required.

A recurrent theme is that Uchimata is not framed as a monolithic end-user platform. Its narrow responsibility is the visualization of 3D models. This suggests a deliberately composable systems role: it is intended to function as a reusable component within larger analytical or visualization pipelines rather than as a self-contained platform with an all-encompassing feature surface.

2. Architecture and implementation model

The toolkit has two components: a web-oriented rendering library and a notebook-oriented Python widget. This split embodies the paper’s explicit separation of concerns between browser visualization and Python-based data analysis.

Component	Primary environment	Implementation and distribution
JavaScript library	Standard web applications, browser-based interactive environments, Observable Notebooks	Implemented in TypeScript, transformed into a JavaScript module, distributed on NPM, uses three.js with a WebGL backend
Python/Jupyter widget	Python computational notebooks, especially Jupyter	Built using anywidget, uses the JavaScript library to serve the visualization canvas within a notebook cell, distributed on PyPI

The JavaScript library is the rendering core. It is responsible for taking 3D genome structural data, applying visual encodings, filtering and querying structure data, and rendering interactive 3D scenes in the browser. Because it is a normal JavaScript module, it can be embedded in custom web applications, genome browsers, data portals, and grammar-based genomics visualization systems.

The Python widget wraps the JavaScript renderer for notebook use. This architecture lets the JavaScript and browser stack handle the UI and rendering layer, while the Python stack handles data wrangling, scientific computing, and bioinformatics workflows. The paper treats that division as a central design principle rather than an incidental implementation choice (Kouřil et al., 16 Sep 2025).

Rendering is done with three.js using WebGL. The paper also notes a planned transition to WebGPU as browser support matures. No quantitative rendering benchmarks are reported, but the choice of a browser-native GPU-accelerated stack indicates attention to practical deployment and future extensibility.

3. Data model and declarative visual specification

At its core, a 3D genome structure is represented as a list of XYZ coordinates, sometimes associated with genomic coordinates. A scene contains an array of structures, and each structure is paired with a view config. The structure supplies the underlying spatial data, whereas the view config specifies how that data is rendered.

In the rendering and query layer, Uchimata uses Apache Arrow tables to represent the 3D structures and associated data. On the Python side, the principal inputs are NumPy arrays and pandas DataFrames. The adoption of Arrow, pandas, and NumPy is presented as an interoperability decision: rather than inventing a custom ecosystem, the toolkit uses established in-memory structures that already align with scientific Python practice and with genomics annotations, which are naturally tabular (Kouřil et al., 16 Sep 2025).

A major feature of the API is its grammar-of-graphics orientation. The toolkit separates the data, the marks used to depict the data, and the visual channels that encode attributes. Users specify a view config that maps structure items to mark types and visual attributes. The paper explicitly names marks such as spheres and cubes, and visual features such as color and scale. This gives the system a declarative quality that is more expressive than a fixed-function viewer and more reproducible than purely ad hoc styling.

The significance of this design is not confined to local customization. The paper reports that Uchimata was used to extend the Gosling grammar with support for 3D genome models, implementing the previously missing “spatial” layout for genomic coordinate systems. That result places the toolkit within a broader ecosystem of declarative genomics visualization rather than limiting it to direct imperative rendering.

4. Filtering, query execution, and interaction

Filtering is one of the toolkit’s headline capabilities, and the paper distinguishes two selection classes: filtering based on genomic semantics and filtering based on spatial properties. This dual model is important in 3D genomics because analysis often alternates between questions defined in linear genomic coordinates and questions defined in physical 3D space.

Genomic-semantic filtering operates through tabular interval logic. In Python workflows, genomic intervals can be loaded and manipulated through bioframe from formats such as BED, GFF, and GTF. Bioframe represents these intervals as pandas DataFrames, and Uchimata accepts those DataFrames as selection queries. It then outputs the corresponding bins of the 3D structure. The same genomic selection can therefore be applied across multiple structures, which supports comparison within ensembles of simulated or inferred conformations (Kouřil et al., 16 Sep 2025).

Spatial filtering is currently implemented through cutting-plane, or cross-section, operations and through selection of spherical neighborhoods of a specified radius. The cutting-plane operation supports slicing the structure to expose internal regions, while spherical neighborhood selection supports queries for bins near a chosen location. The paper emphasizes these as direct means to move from genomic to spatial interrogation and back again.

The underlying query engine is DuckDB operating over Apache Arrow tables. The paper does not present SQL examples or benchmark numbers, but it explicitly describes DuckDB as the mechanism used to perform a variety of queries over the in-memory tabular representation of structures and associated data. A plausible implication is that Uchimata prefers a database-style filtering layer over object-by-object iteration.

The interaction vocabulary described in the paper is intentionally modest. It includes interactive rendering in browser contexts, genomic-coordinate-based selection, spatial filtering, use inside notebook cells for iterative exploratory analysis, application of the same selection across multiple structures, and custom visual encoding through configuration. The paper does not enumerate camera controls, brushing, hover tooltips, animation, or linked highlighting, and those features should therefore not be assumed.

5. Integration with computational genomics workflows

The notebook integration is one of the paper’s central contributions because computational biology workflows frequently generate or analyze 3D genome structures in Python. In that setting, users need to inspect structures immediately, perform basic quality checks, alter simulation parameters, rerun analyses, combine visualization with genomics and statistics tools, and compare multiple structures without leaving the notebook environment. Uchimata is designed around these in-memory workflow assumptions rather than around repeated export and import cycles (Kouřil et al., 16 Sep 2025).

On the browser side, the JavaScript package is intended to behave as a normal dependency in modern web development. The paper discusses use in ordinary web applications, Observable Notebooks, genome browsers, data portals, and case-specific interfaces. The public documentation site hosts examples, and the source for those examples is in the JavaScript repository’s docs folder.

A concrete integration achievement is the extension of Gosling with 3D genome support. Because Gosling is a grammar-based genomics visualization system, that integration demonstrates that Uchimata can function as a rendering substrate inside higher-level declarative environments. The paper further identifies future directions in tighter linking between traditional genome browser views, dense multiscale matrix viewers, and 3D structure visualizations. This suggests that coordinated 2D/3D genomics interfaces are a likely next development frontier.

The toolkit is motivated by 3D structures generated by data-driven methods satisfying experimental constraints such as Hi-C, by de novo mechanistic simulations, and by emerging machine learning-based structure inference. The paper references yeast genome models from Duan et al., mouse single-cell Hi-C structures from Stevens et al., and single diploid human cell structures from Tan et al. as examples of the kinds of structures for which the toolkit is relevant.

6. Biological examples, software availability, and terminology

Figure 1 of the paper functions as both a feature summary and a biological use-case overview. One example uses structures from Stevens et al.’s mouse cells and encodes each chromosome’s coordinates with a continuous color scale; this reveals locations where telomeres concentrate. Another example loads gene annotations from a GTF, aggregates them into bins matching the structure resolution, and maps gene density to both color and scale. In that visualization, gene-rich regions concentrate toward the center of the genome structure, away from the boundary. The paper further notes that scaling marks can reduce occlusion and emphasize internal structure (Kouřil et al., 16 Sep 2025).

These examples illustrate the paper’s broader claim that Uchimata is not merely a low-level 3D renderer. Because visual encodings can be driven by genomic annotations and because selections can be made through both interval semantics and spatial criteria, the toolkit supports exploratory analysis of chromosome territories, telomere arrangements, gene-rich versus gene-poor regions, ensemble comparisons, and local spatial neighborhoods. The examples also show why the view-config model matters: biological interpretation depends on explicit mappings from annotations or coordinate progression to color and scale.

The software is released under the MIT License. The JavaScript library is available on NPM, the widget is available as a Python package on PyPI, and the source code is publicly hosted at https://github.com/hms-dbmi/uchimata and https://github.com/hms-dbmi/uchimata-py. Documentation with examples is hosted at https://hms-dbmi.github.io/uchimata/. The paper provides contact addresses at [email protected] and [email protected].

The paper does not provide numeric benchmarks, runtime measurements, memory measurements, user studies, or comparative performance evaluations. It also does not emphasize native support for many structure file formats, noting instead that structures may exist in diverse formats such as PDB and that the toolkit avoids implementing custom loaders for the many source formats in circulation. Its current rendering backend is WebGL, with WebGPU identified as a future direction. These limitations are consistent with the paper’s characterization of Uchimata as focused infrastructure rather than as a full, feature-complete end-user platform.

The same term also appears, with the spelling Uchi-mata, in judo biomechanics literature. In that separate context, Uchi-mata is discussed as a highly used competition throw, is classified as a couple-of-forces throw, and is analyzed in relation to grips, first-contact tactics, and sagittal-plane application (Sacripanti, 2014). The overlap is therefore terminological rather than methodological: in arXiv usage, “Uchimata” may denote either a 3D genome visualization toolkit or, in another disciplinary literature, a judo technique.