Ketcher
Web-based molecule sketcher
Install / Use
/learn @epam/KetcherREADME
Ketcher 
Ketcher is an open-source web-based chemical structure editor incorporating high performance, good portability, light weight, and ability to easily integrate into a custom web-application. Ketcher is designed for chemists, laboratory scientists and technicians who draw structures and reactions.
Key Features
- ⚡️ Fast 2D structure representation that satisfies common chemical drawing standards
- :diamond_shape_with_a_dot_inside: 3D structure visualization
- :memo: Template library (including custom and user's templates)
- 🔩 Add atom and bond basic properties and query features, add aliases and Generic groups
- :cyclone: Stereochemistry support during editing, loading, and saving chemical structures
- :loop: Storing history of actions, with the ability to rollback to previous state
- :floppy_disk: Ability to load and save structures and reactions in MDL Molfile or RXN file format, InChI String, ChemAxon Extended SMILES, ChemAxon Extended CML file formats
- :microscope: Zoom in/out, hotkeys, cut/copy/paste
- :crystal_ball: OCR - ability to recognize structures at pictures (image files) and reproduce them
- :clipboard: Copy and paste between different chemical editors
- 🛠️ Settings support (Rendering, Displaying, Debugging)
- :camera: Use of SVG to achieve best quality in-browser chemical structure rendering
Editor builtin tools:
- Atom Tool, Bond Tool, and Template Tool to draw and edit structures
- Aromatize/De-aromatize Tool
- Calculate CIP Descriptors Tool
- Structure Check Tool
- MW and Structure Parameters Calculate Tool
- Select, modify, and erase connected and unconnected atoms and bonds using Selection Tool, or using Shift key
- Advanced Structure Clean up Tool (+ stereochemistry checking and structure layout)
- Simple Structure Clean up Tool (checks bonds length, angles and spatial arrangement of atoms)
- Easy to use R-Group and S-Group tools (Generic, Multiple group, SRU polymer, peratom, Data S-Group)
- Reaction Tool (reaction generating, manual and automatic atom-to-atom mapping)
- Flip/Rotate Tool
Installation and usage
At this moment Ketcher can be embedded into your application in two ways:
- as ready-to-run application (to find desired version please look at Assets block of releases). The application can be injected as IFrame or a separate page.
- as a react component library
Installation
npm install ketcher-core ketcher-react
Basic Setup
import { Editor } from 'ketcher-react';
import { StandaloneStructServiceProvider } from 'ketcher-standalone';
import 'ketcher-react/dist/index.css';
const structServiceProvider = new StandaloneStructServiceProvider();
function App() {
return (
<Editor
staticResourcesUrl="/public"
structServiceProvider={structServiceProvider}
onInit={(ketcher) => {
window.ketcher = ketcher;
}}
/>
);
}
FAQ
How to use react component library
Look at the following link for details.
Configure indigo service
You can find the instruction for service installation here.
Packages
| Project | Status | Description |
|-------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|
| ketcher-core | 
| Core functionality: domain, shared services, functions and interface declarations |
| ketcher-standalone | 
| Contains only the functionality necessary to start Ketcher in standalone mode |
| ketcher-react | 
| Package contains only the functionality necessary to define components. |
| ketcher-macromolecules | 
| Package contains the macromolecules editor functionality and UI components |
3D Viewer
Ketcher uses Miew-React for viewing and editing data in 3D.
You can find the latest version of Miew-React here. The last checked version - 1.0.0.
Macromolecules mode
Starting with version 3.0, Ketcher supports a new control in the top toolbar that allows switching to macromolecules editing mode. If you prefer having only small molecules editing mode available, you can remove the mode switcher from the toolbar by passing disableMacromoleculesEditor property to the Editor component.
import { Editor } from 'ketcher-react';
const App = () => {
return (
<Editor
{/* ...rest of the properties */}
disableMacromoleculesEditor
/>
);
};
Please refer to the example/src/App.tsx file for a complete example of how to integrate Ketcher editor into your application.
Ketcher API
- Structure Export Methods
- Structure Import Methods
- Editor Operations
- View Control
- Settings Management
- Event System
- React Component API
- Macromolecules Mode
- Service Providers
- Supported Formats
- Usage Examples
- Internal Services (Advanced)
- Error Handling
Structure Export Methods
All export methods return Promise<string> with the structure in the requested format.
getSmiles
getSmiles(isExtended?: boolean): Promise<string>
Returns SMILES (Simplified Molecular Input Line Entry System) representation.
Parameters:
isExtended(optional) - Use extended SMILES format (default:false)
Throws: Error in macromolecules mode
Example:
const smiles = await ketcher.getSmiles();
// Returns: "C1=CC=CC=C1"
const extended = await ketcher.getSmiles(true);
// Returns extended SMILES with stereochemistry
getExtendedSmiles
getExtendedSmiles(): Promise<string>
Alias for getSmiles(true).
getMolfile
getMolfile(molfileFormat?: 'v2000' | 'v3000'): Promise<string>
Returns MDL MOL file format.
Parameters:
molfileFormat(optional) - MOL file version:'v2000','v3000', or auto-detect
Throws: Error if structure contains reaction arrows (use getRxn instead)
Example:
const mol = await ketcher.getMolfile('v3000');
getRxn
getRxn(molfileFormat?: 'v2000' | 'v3000'): Promise<string>
Returns RXN (Reaction) file format.
Parameters:
molfileFormat(optional) - RXN file version (default:'v2000')
Throws:
- Error if no reaction arrows present
- Error in macromolecules mode
Example:
const rxn = await ketcher.getRxn('v3000');
getKet
getKet(): Promise<string>
Returns KET (Ketcher JSON) format - the native internal format.
Works in both micro and macromolecules modes.
Example:
const ket = await ketcher.getKet();
const ketObj = JSON.parse(ket);
getSmarts
getSmarts(): Promise<string>
Returns SMARTS (SMILES Arbitrary Target Specification) representation.
Throws: Error in macromolecules mode
getCml
getCml(): Promise<string>
Returns CML (Chemical Markup Language) format.
Throws: Error in macromolecules mode
getSdf
getSdf(molfileFormat?: 'v2000' | 'v3000'): Promise<string>
Returns SDF (Structure-Data File) format.
Parameters:
molfileFormat(optional) - Version (default:'v2000')
Throws: Error in macromolecules mode
getRdf
getRdf(molfileFormat?: 'v2000' | 'v3000'): Promise<string>
Returns RDF (Reaction Data File) format.
Parameters:
molfileFormat(optional) - Version (default:'v2000')
Throws: Error in macromolecules mode
getCDXml
getCDXml(): Promise<string>
Returns CDXML (ChemDraw XML) format.
Throws: Error in macromolecules mode
getCDX
getCDX(): Promise<string>
Returns CDX (ChemDraw binary) format as base64-encoded string.
Throws: Error in macromolecules mode
