# Ketcher

## Specs

| Label                     | Value                         |
| ------------------------- | ----------------------------- |
| **Version**               | 0.1.0 (updated on 2026-04-20) |
| **Developer**             | Labii Inc.                    |
| **Type**                  | Section                       |
| **Support Configuration** | No                            |

## Overview

The Labii Ketcher Chemical Structure Drawing widget integrates the open-source [Ketcher](https://github.com/epam/ketcher) editor by EPAM Systems directly into the Labii platform, enabling chemists, laboratory scientists, and technicians to draw, edit, and save chemical structures and reactions within their electronic lab notebook or data management workflows. Ketcher delivers high performance, excellent portability, and a rich set of built-in tools covering everything from simple atom and bond placement to advanced stereochemistry, R-group/S-group handling, and reaction mapping. Structures are stored in standard chemical file formats — including MOL, SMILES, InChI, and KET — ensuring seamless interoperability with analysis pipelines and external chemical databases. As a fully browser-based, open-source editor, Ketcher requires no additional license and works out-of-the-box inside Labii.

{% hint style="warning" %}
ChemDraw, LabSketch, JSME Molecular Editor, Kekule, and Marvin JS widgets have been retired. Use the Ketcher widget for chemical structure drawing in Labii.
{% endhint %}

## Use Cases

* **Structure Documentation:** Draw and save chemical structures as part of experiment notes, synthesis records, or compound registration entries.
* **Reaction Design:** Sketch multi-step reactions with reactants, products, and mechanisms using built-in reaction tools and automatic atom-to-atom mapping.
* **Compound Registration:** Use Ketcher in conjunction with Labii's inventory or chemical registration applications to capture and manage new molecular entities.
* **Substructure & Similarity Search:** Store structures in searchable SMILES or MOL format to enable substructure and Tanimoto-based similarity searches across compound libraries.
* **Property Calculation:** Calculate molecular weight, monoisotopic mass, molecular formula, and mass composition directly within the editor.
* **OCR Structure Recognition:** Recognize and reproduce chemical structures from image files using the built-in OCR tool.
* **Macromolecule Editing:** Switch to macromolecules mode to draw and document peptides, nucleic acids, and other biological polymers in FASTA, HELM, or sequence formats.
* **Template-Based Drawing:** Accelerate structure entry using the built-in template library, including ring systems and functional group fragments, or create custom user templates.

## Interface

### Read-only View

In read-only mode, the saved chemical structure is rendered as a high-quality SVG depiction directly within the section. The structure is displayed at its natural scale with clean bond-length proportions and stereochemistry indicators. Users can zoom in or out of the rendered image for closer inspection. No editing controls are visible in this state, keeping the record view clean and focused on the documented structure.

<figure><img src="/files/Cauw9sZRSNmE9Vl4Fc8H" alt="Read-only view of the Ketcher widget showing a rendered chemical structure"><figcaption><p>The read-only view displays the saved chemical structure as an SVG rendering with stereochemistry and bond-order information.</p></figcaption></figure>

### Edit View

Clicking **Edit** on the section loads the full Ketcher editor canvas. The edit view provides:

* **Drawing Toolbar** — Atom tool, Bond tool, Template tool, Erase tool, Selection tool, and Reaction tool for comprehensive structure authoring.
* **Top Toolbar** — Actions including Undo/Redo, Cut/Copy/Paste, Zoom controls, Open/Save file, Aromatize/De-aromatize, CIP descriptor calculation, Structure Check, Molecular Properties, Auto-layout, and Structure Clean-up.
* **Template Library** — Access a curated panel of common ring systems, functional groups, and user-saved templates to accelerate drawing.
* **AI Prompt Box** — Generate structures from a text description using Labii's AI integration.
* **File Import** — Drag and drop or click the cloud icon to import MOL, SDF, CML, InChI, or SMILES files.
* **Save Button** — Commit the current canvas to the Labii record.
* **Substructure Search / Similarity Search** — Launch cross-table chemical searches directly from the editor toolbar.

<figure><img src="/files/Kpds52S3dFoPCYU4mWwZ" alt="Edit view of the Ketcher widget showing the full drawing canvas and toolbar"><figcaption><p>The edit view provides the complete Ketcher drawing environment with all structure-editing tools accessible from the toolbar.</p></figcaption></figure>

## Configuration

The Ketcher widget functions out-of-the-box without requiring additional configuration.

{% hint style="info" %}
Unlike some other Labii chemical drawing widgets, Ketcher is fully open-source (Apache 2.0) and does not require a third-party license. It is ready to use immediately after enabling the widget on a section.
{% endhint %}

## Additional Functions

### Save

Click the **Save** button in the Ketcher toolbar to commit the current structure to the Labii record. The structure is stored in a standard chemical format and rendered as an SVG in the read-only view.

### File Import

Ketcher supports importing the following file formats via the cloud icon or drag-and-drop:

* MOL (V2000 / V3000)
* RXN (reaction files)
* SDF / SD
* CML
* InChI
* SMILES / Extended SMILES
* SMARTS
* KET (Ketcher native JSON)
* CDXML / CDX (ChemDraw)

{% stepper %}
{% step %}
In the edit view, click the **cloud icon** in the toolbar, or drag and drop a supported chemical file onto the canvas.
{% endstep %}

{% step %}
Ketcher automatically detects the file format and renders the structure on the canvas.
{% endstep %}

{% step %}
Review the imported structure, make any edits, then click **Save**.
{% endstep %}
{% endstepper %}

### Generating Chemical Structure with AI

Learn more at [here](https://github.com/Labii/labii-gitbook-docs/blob/gitbook/widgets/section-widgets/chemistry/chemical-drawing.md#generate-chemical-structure-with-ai).

### Substructure Search

Learn more at [here](https://github.com/Labii/labii-gitbook-docs/blob/gitbook/widgets/section-widgets/chemistry/chemical-drawing.md#sub-structure-search).

### Similarity Search

Learn more at [here](https://github.com/Labii/labii-gitbook-docs/blob/gitbook/widgets/section-widgets/chemistry/chemical-drawing.md#similarity-search).

### Molecular Properties Calculation

Ketcher includes a built-in **Analyze Structure** tool that calculates key molecular properties directly on the canvas:

* Molecular weight
* Monoisotopic mass
* Most abundant mass
* Molecular formula (gross formula)
* Mass composition

{% stepper %}
{% step %}
Draw or load a structure in the edit view.
{% endstep %}

{% step %}
Click the **Analyse** button (flask icon) in the top toolbar.
{% endstep %}

{% step %}
A panel displays the calculated molecular weight, formula, and mass values for the current structure.
{% endstep %}
{% endstepper %}

### Stereochemistry and CIP Descriptors

Ketcher supports full stereochemistry editing during structure entry and loading. Use the **Calculate CIP** tool to assign R/S and E/Z descriptors automatically:

{% stepper %}
{% step %}
Draw or load a chiral structure on the canvas.
{% endstep %}

{% step %}
Click the **CIP** button in the top toolbar.
{% endstep %}

{% step %}
Ketcher calculates and labels all stereocenters with their CIP descriptors (R, S, E, Z).
{% endstep %}
{% endstepper %}

### Structure Check

Validate the chemical validity of a structure before saving:

{% stepper %}
{% step %}
Draw or load a structure on the canvas.
{% endstep %}

{% step %}
Click the **Check** button (checkmark icon) in the top toolbar.
{% endstep %}

{% step %}
Ketcher reports any structural issues such as valence errors, incompatible stereochemistry, or ambiguous charges.
{% endstep %}

{% step %}
Correct any flagged issues, then click **Save**.
{% endstep %}
{% endstepper %}

### 3D Structure Visualization

Ketcher integrates with Miew-React for interactive 3D molecular visualization:

{% stepper %}
{% step %}
Draw or load a structure on the canvas.
{% endstep %}

{% step %}
Click the **3D** viewer button (Miew icon) in the top toolbar.
{% endstep %}

{% step %}
The structure opens in an interactive 3D viewer. Rotate, zoom, and explore the molecular geometry.
{% endstep %}
{% endstepper %}

### Undo / Redo

Ketcher maintains a full action history. Use **Ctrl+Z** (Cmd+Z on macOS) to undo and **Ctrl+Y** (Cmd+Y) to redo, or click the corresponding toolbar buttons.

### Zoom Controls

Use the **+** / **−** toolbar buttons or the keyboard shortcuts **Ctrl++** / **Ctrl+−** to zoom in and out of the canvas. The zoom range is 20%–400%.

## Best Practices

### Structure Consistency

* Use a single drawing widget consistently within a project so that substructure search fingerprints remain comparable across records.
* Apply the **Clean Up** tool before saving to normalize bond lengths, angles, and atom placement for a standardized depiction.

### Stereochemistry Documentation

* Always draw wedge and dash bonds explicitly for chiral centers to ensure accurate stereochemistry is recorded.
* Run **Calculate CIP** after drawing chiral structures to verify descriptor assignments before saving.

### Reaction Documentation

* Use the **Reaction Tool** (arrow icon) to draw the full reaction scheme including reagents, conditions, and products in a single canvas entry.
* Apply **Auto-mapping** to establish accurate atom-to-atom correspondence for reaction tracking.

{% hint style="success" %}
Saving structures in SMILES or MOL format enables substructure and similarity searches across Labii tables, significantly accelerating compound lookup and SAR analysis.
{% endhint %}

### File Imports

* Import MOL V3000 files when working with extended atom lists, larger structures, or enhanced stereochemistry annotations.
* Use the KET format for round-tripping structures through Labii without any loss of Ketcher-specific annotations.

### Common Pitfalls to Avoid

* **Avoid** closing the edit view without clicking **Save** — unsaved changes on the canvas will be discarded.
* **Avoid** mixing drawing widgets for the same compound library, as different renderers may generate different fingerprints for the same structure.
* **Instead**, standardize on one drawing widget per section type and use the Clean Up tool before each save.

## Related Widgets

* [**SMILES Drawer**](/widgets/section-widgets/chemistry/chemical-drawing/smiles-drawer.md): Read-only SMILES rendering widget for displaying structures stored as SMILES strings.

## References

* [Ketcher Homepage](http://lifescience.opensource.epam.com/ketcher) — Official project documentation by EPAM Life Sciences.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.labii.com/widgets/section-widgets/chemistry/chemical-drawing/ketcher.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.