epam / epam/ketcher

Introduce the Lone Pair tool

Open
#9,783 4 comments 1 reaction 1 assignee Claimed by @ljubica-milovic View on GitHub
User`s Feedback
Dominant language
TypeScript
Stars
884
Forks
262
Avg merge
3d 10h
Merged PRs (30d)
126

Description

## Background

Users want lone (nonbonding) electron pairs drawn on heteroatoms (e.g. two pairs on oxygen in an alcohol) for teaching and clearer Lewis-style structures. This has been requested before (e.g. [#1383](https://github.com/epam/ketcher/issues/1383)). Today that information is implicit in chemistry/layout but not consistently shown in the editor.

Original user's ticket

Solution

In Molecules mode, add optional lone-pair annotations: pairs of dots outside the atom label, driven by a computed expected lone-pair count (valence, charge, radicals, implicit H, bonds, aromatic rings—with explicit templates where generic aromatic bookkeeping would mis-count).

Settings → Atoms: per-element Show lone pairs for N, O, S, F, Cl, Br, I (default off); controls for dot diameter, offset, and spread; persist with other render settings.
Atom Properties: read-only expected lone pairs; Lone pair display: inherit / show / hide (override vs global toggles).
Toolbar: Toggle Lone Pair Display on supported atoms (not atom lists / R-group labels): click toggles forced show vs hide consistent with the dialog.
Placement: choose among top/right/bottom/left, scored to limit overlap with other labels/charges and to avoid pointing straight along bonds when possible; multiple pairs use distinct directions when possible.
Scope: standard molecule editing/viewing; export of lonePairDisplay follows Ketcher/KET as implemented; other formats may omit unsupported fields.
Alternatives

No feature: rely on implicit valence and layout only (current frustration in [#1383](https://github.com/epam/ketcher/issues/1383)).
Always-on dots with no settings (noisy; bad for publication-style drawings).
External / post-process rendering only (no live feedback in Ketcher).
Additional context

Implementation: PR [#9766](https://github.com/epam/ketcher/pull/9766).

[Indigo ticket](https://github.com/epam/Indigo/issues/3827)

---

## Requirements

$\color{Red}{\textbf{Toolbar icon}}$

1. A new tool should be added to the left toolbar - "Lone Pair" - and be placed below the "Charge Minus" tool.

1.1. Hovering the toolbar icon should give the tooltip "Lone Pair".

---

$\color{Red}{\textbf{Adding lone pairs to an atom}}$

2. Clicking on an atom with the lone pair tool should add a lone pair to the atom.

2.1. The lone pair should be positioned above/below/left/right of the atom label.

Image

2.1.1. The priority of quadrants is: Q1>Q3>Q2>Q4.

2.1.2. Place the lone pair in the quadrant with the highest priority that doesn't have bonds (of that atom) AND doesn't have a radical.

> Radicals are always placed in Q1.

2.1.3. If the atom doesn't have a radical, and no quadrant described in the previous requirement exists, place the lone pair in the quadrant with the highest priority.

2.1.4. If the atom has a radical, and no quadrant described in 2.1.2. exists, place the lone pair in the quadrant with the highest priority (excluding Q1).

2.2. If the atom already has 4 lone pairs OR 3 lone pairs and a radical, clicking on the atom with the lone pair tool should remove all of them.

---

$\color{Red}{\textbf{Atom Properties window}}$

3. A new property should be added to the "Atom Properties" window, in the "General" section, and below "Radical".

3.1. The property should be called "Lone Pair", and have a dropdown with options: _Blank_ (default), "1", "2", "3", and "4".

3.1.1. If the atom has a radical set, the option "4" should be disabled.

3.2. The option should reflect how many lone pairs the atom currently has, and the change in the menu should add/remove lone pairs.

3.2.1. The logic for what lone pair should get removed is the opposite of addition (reqs. 2.1.).

---

$\color{Red}{\textbf{Settings}}$

4. A new setting should be introduced "Lone pair representation" - the option should be placed in the "Atoms" section, below "Display Valence", and have three options in the drop-down: "On" (default), and "Off".

4.1. If "Off" is selected, the lone pairs shouldn't be shown.

> This setting should be passed to Indigo for rendering.

---

$\color{Red}{\textbf{Varning for incorrect amount of lone pairs}}$

5. After change* to a single periodic table atom a "valence" check should be performed to check if the arrangement is possible.

> All atoms (inc. atom lists and query atoms) can have lone pairs assigned to them, just like valence, radicals, charges etc. But this check can only be performed with "real" atoms.

> '* Change is considered any change to the atom type, adding/removing bonds, charges, and radicals.

5.1. Maximum number of lone pairs on an atom is nMAXLonePairs = rounddown (Elremaining/2), calculated using the formula form [a previous ticket](https://github.com/epam/ketcher/issues/10427):

Elremaining = El0 $\color{Blue}{\textbf{- charge}}$ $\color{Green}{\textbf{- bonds}}$ $\color{Red}{\textbf{- radicals}}$ $\color{Pink}{\textbf{- 2 * number of donor dative bonds}}$, with the $\color{Green}{\textbf{- bonds}}$ factor this time including implicit hydrogens.

> Lone pairs will not impact valence, hence the inclusion on implicit hydrogens in the calculation, and why "valence" check is in quotation marks.

5.2. If the atom has more than nMAXLonePairs lone pairs drawn, the atom should be underlined as if it has a valence warning.

5.2.1. Tooltip for atoms with an underline should say: "This atom has an incorrect amount of lone pairs."

5.3. A tooltip for incorrect valence should be introduced - every atom that is underlined because of valence should have a tooltip: "This atom has an incorrect valence."

5.3.1. If the atom has both incorrect valence and an incorrect amount of lone pairs, the tooltip should be: "This atom has incorrect valence and incorrect amount of lone pairs."

---

$\color{Red}{\textbf{KET file}}$

6. Ketcher should have the ability to save/load KET files with atoms that have lone pairs.

---

## Design

Image

Image

Image

Image

Image

Image

Image

Image

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.