Skip to content
Back to search

chemdraw-figures

Draw chemistry figures (reaction schemes, rows of literature reactions, catalytic cycles, metal–π complexes, reaction energy profiles from DFT energies, transition-state structures) as editable ChemDraw CDXML plus a PNG, using the cdxkit Python library in this folder. Use when the user asks to draw, redraw or tidy a ChemDraw figure, scheme, catalytic cycle or energy profile (also in Chinese, e.g. "画 ChemDraw 图", "画个催化循环", "画能量图", "照第 1 章那种风格画", "按刘组规范画"). Styles are optional: use a style from styles/ only when the user names it; if no style is named, ask once which style to use before drawing.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ruiqi-ding-chem--chemdraw-figure-kit/badge.svg)](/listings/ruiqi-ding-chem--chemdraw-figure-kit)

HTML

<a href="/listings/ruiqi-ding-chem--chemdraw-figure-kit"><img src="/api/listings/ruiqi-ding-chem--chemdraw-figure-kit/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/Ruiqi-Ding-chem/chemdraw-figure-kit.git
cd chemdraw-figure-kit
pip install -r requirements.txt        # numpy, matplotlib, rdkit
python examples/02_literature_rows.py  # writes examples/out/02_literature_rows.cdxml + .png

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 241 lines
  1. ---
  2. name: chemdraw-figures
  3. description: Draw chemistry figures (reaction schemes, rows of literature reactions, catalytic cycles, metal–π complexes, reaction energy profiles from DFT energies, transition-state structures) as editable ChemDraw CDXML plus a PNG, using the cdxkit Python library in this folder. Use when the user asks to draw, redraw or tidy a ChemDraw figure, scheme, catalytic cycle or energy profile (also in Chinese, e.g. "画 ChemDraw 图", "画个催化循环", "画能量图", "照第 1 章那种风格画", "按刘组规范画"). Styles are optional: use a style from styles/ only when the user names it; if no style is named, ask once which style to use before drawing.
  4. ---
  5. # ChemDraw figures with cdxkit
  6. cdxkit turns a short Python description of a figure into two files: a CDXML that opens in
  7. ChemDraw and stays fully editable, and a PNG rendered to look like ChemDraw (600 dpi). The
  8. library is in `cdxkit/` next to this file; the examples in `examples/` are the fastest way to
  9. see how a figure is built.
  10. ## 1. Settle content and style first
  11. - **Content.** Which reactions, structures, conditions and numbers go in, and where each one
  12. comes from (a paper, the user's own ChemDraw file, their notes). If something is missing,
  13. ask; never fill in a yield, condition or structure from memory.
  14. - **Style.** Styles live in `styles/`. Use one only when the user asks for it by name (or
  15. says e.g. "like Chapter 1", "第 1 章那种风格" → `styles/literature-rows.md`). If the user
  16. did not name a style, ask once, offering:
  17. - `acs-plain`: ChemDraw's ACS Document 1996 defaults, black only (`styles/acs-plain.md`);
  18. - `literature-rows`: one literature reaction per row, a few colours with fixed meanings,
  19. curved in/out arrows on cycles (`styles/literature-rows.md`);
  20. - `liu-group`: computational figures, i.e. energy profiles, transition states and
  21. intermediates, following the Liu group SOPs (`styles/liu-group.md`; also "刘组风格");
  22. - match a figure or spec the user provides.
  23. Do not apply colours or layout conventions from a style the user did not choose. For an
  24. energy profile with no style named, offer liu-group first: it is the only style with rules
  25. for profiles.
  26. ## 2. Rules that hold in every style
  27. 1. **Faithful to the source.** Draw each structure as the source draws it: same orientation,
  28. same stereochemistry (do not mirror or flip a product "to fit"; a flipped drawing suggests
  29. a different stereoisomer). Copy conditions and numbers exactly, and say what a number is
  30. (isolated vs NMR yield, d.r., ee). If the source is not available, say so instead of
  31. guessing.
  32. 2. **Consistent within a figure.** The same kind of thing is drawn the same way everywhere
  33. in one figure (do not show one compound as a structure and another as a condensed formula;
  34. same abbreviation, same bond length, same label style).
  35. 3. **Labels read correctly.** A label is written so that the bonded atom touches the bond:
  36. - bond from the right → `OTIPS` becomes `TIPSO`;
  37. - bond from the left → start with the bonded atom, e.g. `Fe(CO)<sub>2</sub>Cp*`;
  38. - bond from above or below → start with the bonded atom and left-align it, e.g.
  39. `('OBBu<sub>2</sub>', 'left')`.
  40. Write labels as they should appear. In the CDXML, cdxkit stores a label that sits left of
  41. its bond in ChemDraw's typed order (`TIPSO` is stored as `OTIPS`), because ChemDraw reads
  42. labels that way when it opens or saves a file. Do not reverse labels yourself.
  43. 4. **Look at it.** Always render the PNG and view it before showing it to the user. Check
  44. for: reversed or misplaced labels, overlapping text, arrows that do not reach, crowded
  45. conditions, rows that are not centred, empty space on one side.
  46. 5. **Check the file.** `layout.save()` prints `name: self-check PASS` plus any `WARNING:` lines.
  47. - PASS means the CDXML reads back with RDKit with the same nodes, bonds and organic skeleton
  48. (fragments made only of labels such as `[Fe]`, `L`, `Ar` are checked for counts only). It
  49. says nothing about how the PNG looks.
  50. - Two warnings concern bonds squeezed between labels; in both cases lengthen the bond
  51. (`L.ML` for metal bonds) or move the labels:
  52. - "bond X-Y … is hidden by its labels": the bond is missing from the PNG (it is still in
  53. the CDXML);
  54. - "bond X-Y … shows only n pt between its labels": the bond is too short to read. A
  55. dashed TS bond shorter than about 4 pt looks solid.
  56. - On Windows with ChemDraw installed, `cdxkit.chemdraw.export()` opens the CDXML in ChemDraw
  57. and saves a ChemDraw-rendered PNG/CDX. It refuses to run while ChemDraw is already open
  58. (the user may have unsaved work) and never quits a ChemDraw it did not start.
  59. 6. **Hand over** the `.cdxml` (for editing in ChemDraw) and the `.png`, and list anything the
  60. user should still adjust by hand (see Limitations).
  61. ## 3. Using the library
  62. ```python
  63. import sys; sys.path.insert(0, r'<this skill folder>')
  64. from cdxkit import Scene, mid, register_color
  65. from cdxkit import layout as L
  66. from cdxkit.cycle import Cycle
  67. s = Scene() # ACS 1996: Arial 10 pt, bond 14.4 pt
  68. m, box = L.place(s, 'C=CCC', 10, 60) # SMILES -> atoms; box = ink bbox
  69. fe = s.add_atom_label(*L.metal_above(m[0], m[1]), '[Fe]<sup>+</sup>')
  70. L.eta2(s, fe, m[0], m[1]) # dashed eta-2 line to the C=C midpoint
  71. L.add_h(s, m[2], deg=-90, color='red') # explicit H (optional colour)
  72. x = L.arrow_with_conditions(s, box[2] + 12, 60, above=['Et<sub>3</sub>N'], below=['CH<sub>2</sub>Cl<sub>2</sub>'])
  73. L.place(s, '*CC=CC', x + 12, 60, labels={0: '[Fe]'})
  74. L.save(s, 'out/figure') # out/figure.cdxml + .png, prints self-check
  75. ```
  76. Coordinates are points (1/72 in), y grows downwards; angles are degrees counter-clockwise on
  77. paper (0 = right, 90 = up).
  78. **Atoms are found by position.** `add_bond(p1, p2)` connects whatever atom sits at p1/p2
  79. (within 0.6 pt), so never draw a second fragment on top of an existing one ("draw at the
  80. origin, move later" goes wrong). Draw each part at its final position, or draw it in its own
  81. `Scene` and copy it in with `L.merge(s, part, dx, dy)`; `RowFigure` already does this for
  82. every row. The library warns when an atom lands on another one, and `save()` lists labels
  83. left without bonds. Text accepts `<sub> <sup> <i> <b>`, `\n`, and HTML entities
  84. (`&#8242;` ′, `&#960;` π, `&#176;` °).
  85. | Need | Call |
  86. |---|---|
  87. | sizes | `L.BL` = 14.4 pt (C–C bond), `L.ML` = 21 pt (metal–ligand bond) |
  88. | molecule from SMILES | `L.place(s, smi, left, cy, rotate=, flip=, labels={i: 'Ar'}, align_atom=None)` → (AtomMap, ink box); `cy` centres the ink box, or puts atom `align_atom` at height cy (to sit a chain on the arrow axis). `L.place_center(...)`; `L.ink_size(smi)`; `L.orient(smi, i, j, deg, flip=)` gives the `rotate` that points bond i→j at deg (pass the same flip as to place). AtomMaps are snapshots: after moving atoms, look them up again. A metal on a `*` gets a C–C length bond; lengthen it with `L.stretch(s, m[c], m[star], L.ML)`. Put abbreviations on `*` atoms; give stereo in the SMILES, e.g. SMILES `C/C=C(\*)c1ccccc1` (in a Python string `'C/C=C(\\*)c1ccccc1'`). |
  89. | hand-drawn fragment | `s.add_atom_label(x, y, text, align=None|'left'|'right'|'center')` (None = automatic, the default), `s.add_bond(p1, p2, order=1|2|3, style='solid'|'dashed'|'wedge'|'hash'|'bold', pos=, color=)`, `s.set_bond(p1, p2, ...)`, `L.phenyl(s, p, deg)`, `L.stretch(s, p_fixed, p_move, length)` |
  90. | colour a label / bond | `s.paint(p, 'navy')` (atom label at p), `s.color_bond(p1, p2, 'red', style='bold')` |
  91. | point at an angle | `L.pol(p, deg, d=L.BL)` |
  92. | metal on a π bond | `L.metal_above(a1, a2)`, `L.eta2(s, metal, a1, a2)` |
  93. | explicit H | `L.add_h(s, p, deg=None, color=None)` (deg=None: open direction) |
  94. | allene centre dot | `L.allene_dot(s, p)` |
  95. | arrows | `L.arrow_with_conditions(s, x1, y, above=[...], below=[...], eq=False)`, `s.add_arrow(x1, y1, x2, y2, head='full'|'half'|'none', dashed=, bold=, lw=)` (head='none' = Line tool; bold=True = ChemDraw Bold line), `s.add_arc_arrow(cx, cy, r, a0, a1, head=, head_size=(800, 700, 200))`, `s.add_eq_arrows(...)`, `L.line(s, p, q, dashed=True)` (plain line, not a bond) |
  96. | chair / boat (six-membered cyclic TS) | `L.chair(center, side=L.ML, mirror=False, flip=False)` → 6 positions in ring order (plain-line textbook chair); `L.boat(center, side=, mirror=, flip=)` → positions of ChemDraw's boat template (draw front edge bold, tip-to-front edges as wedges; see docstring). `L.polygon(center, n, side=)` is for planar rings only |
  97. | energy profile | see "Energy profiles" below |
  98. | text | `s.add_text(x, y, text, align=, valign='baseline'|'center', color=, size=)` → ink box; `L.caption_under(s, box, text, dy=)`, `L.plus(s, x, y)`, `L.text_lines(...)`, `L.text_width(text)`, `L.wrap(text, width)` |
  99. | boxes | `L.fill_box(s, box_or_Mark, pad=4, fill='fill')` (tile behind a structure), `s.add_rect(x, y, w, h, fill=, dashed=, rounded=)`, `L.label_box(s, x_right, y_base, text, fill)`, `s.add_bracket(...)`, `L.via_bracket(s, box)` |
  100. | colours | palette names `red navy grey fill rule redfill navyfill greyfill darkblue darkred` (`grey` = #797979, `darkblue` #011993 and `darkred` #941100 are the liu-group pathway colours); more with `register_color('teal', '#13786F')` |
  101. | one row per reaction | `L.RowFigure(width=468, title_position='top'|'left', row_gap=10, rule_color='rule'|None, tag_color=).row(title, draw_fn, tag=, align='center'|'left')` then `.build()`. Each `draw_fn(part)` draws in its own scene at any coordinates; the row is measured, centred and merged in. Titles are bold 10 pt, tags italic. For acs-plain use `rule_color=None`. |
  102. | combine pieces | `L.merge(s, part, dx, dy)` copies scene `part` into `s` |
  103. | catalytic cycle | see "Catalytic cycles" below |
  104. | move / measure a part | `mk = L.Mark(s)` … draw … `mk.bbox()`, `mk.shift(dx, dy)` |
  105. | output | `L.save(s, base)` → `base.cdxml`, `base.png` + self-check (`s.check_cdxml` needs `s.to_cdxml` first; `save` does both); `cdxkit.chemdraw.export(cdxml, [png, cdx])` |
  106. ### Metal centres and labels
  107. - Atom labels are anchored automatically:
  108. - a label or metal symbol bonded on both sides, or with three or more bonds, is centred on
  109. the atom (`Ar–Pd–X` with two `PPh3`, `L–Pd<sup>II</sup>–L`);
  110. - a label whose bond comes from the right is right-aligned (`Fp–CH2`, `TIPSO–`);
  111. - otherwise it is left-aligned, so the first character sits on the atom (`PPh3` above or
  112. below a metal).
  113. Override with `align='left'|'right'|'center'`. A label cannot be anchored on a character in
  114. its middle (e.g. the Fe of `Cp*Fe(CO)2`); write it so that the bonded atom comes first or
  115. last.
  116. - Use `L.ML` for metal–ligand bonds. If two labels end up so close that the bond between them
  117. would vanish, `save()` warns.
  118. ### Catalytic cycles
  119. ```python
  120. cyc = Cycle(s, cx, cy, r, clockwise=True, hook_radius=17, hook_sweep=72)
  121. cyc.arc(62, 16) # arc arrow, head at 16 deg (clockwise)
  122. cyc.hook(54, 'in', 'base') # reagent joins at 54 deg
  123. cyc.hook(34, 'out', 'BH<sup>+</sup>') # by-product leaves at 34 deg
  124. cyc.hook(148, 'in', draw_fn) # draw_fn(scene, (x, y)): a structure
  125. cyc.label(26, 'deprotonation', dist=8, color='navy') # step name inside, next to its arc
  126. ```
  127. - A hook touches the cycle at `theta` and curls outwards. For a clockwise cycle the free end
  128. of an `'in'` hook lies upstream (counter-clockwise of theta) and that of an `'out'` hook lies
  129. downstream. Pick theta so the free end lands in empty space.
  130. - The label or structure goes beyond the free end: to its right on the right half of the
  131. cycle, to its left on the left half, centred near the top and bottom. Force a side with
  132. `side='left'|'right'|'center'`; `gap=` sets the distance; `head_in='full'` puts a head on an
  133. 'in' hook.
  134. - `cyc.label` accepts multi-line text (`'reductive\nelimination'`) and keeps wide text near
  135. the top and bottom clear of the arc. Increase `dist` if it still touches.
  136. - Typical sizes with 10 pt text: r = 55–65 pt.
  137. ### Energy profiles
  138. ```python
  139. from cdxkit.energy import EnergyProfile, load_energies, common_sides
  140. E = load_energies('energies.csv', column='M06/def2-TZVP') # {label: kcal/mol}, see below
  141. ep = EnergyProfile(energies=E) # liu-group defaults; bars='bonds' optional
  142. ep.path(['1', 'TS1', ('2', None, dict(add='R<sub>2</sub>C=O')), '3', 'TS3a',
  143. ('4a', None, dict(add='R<sub>3</sub>SiH', remove='LCuH')), ('5a', None, dict(shift=25))])
  144. ep.path(['3', 'TS3b', '4b']) # starts at a known label = branches there
  145. ep.structure('TS1', draw_ts1) # draw_ts1(scene) draws the TS anywhere
  146. # ep.note('M06/def2-TZVP/SMD(DCE)//B3LYP-D3(BJ)/6-31G(d)') # only if the user asks for it
  147. ep.save('out/profile') # .cdxml + .png + checks + table of values
  148. ```
  149. - **Numbers.** Take them from the user's table, never from memory or from an old figure.
  150. - The CSV has the label in the first column and one column per method, in kcal/mol relative
  151. to one reference. Columns whose header starts with `#` are notes; an empty cell or n.a.
  152. means no value.
  153. - A step given only by its label is looked up in that table. `('TS1', 12.4)` gives the
  154. value directly; use it only when there is no table.
  155. - The same label in two pathways is one point. It must have the same energy in both; give
  156. different species different labels.
  157. - **Step options** (on the step, as a dict):
  158. - `add=`, `remove=`: a reagent entering or a product leaving on the connector to the next
  159. step;
  160. - `at=`, `curve='above'|'below'`: where on that connector the curve touches (0 to 1), and
  161. on which side of it the curve goes. If either is left out, the library tries positions
  162. and both sides until the curve and its texts touch nothing;
  163. - `shift=`: a scale break on the connector into this step; this and later steps are drawn
  164. that many kcal/mol higher;
  165. - `x=`: the column slot;
  166. - `side='above'|'below'`: put both texts on that side of the bar;
  167. - `text=`: how the number is printed, e.g. `'TS2-<i>cis</i>'`;
  168. - `dh=`: ΔH, printed in parentheses under ΔG.
  169. - **`EnergyProfile` options:**
  170. - `columns=1|2`, `span=`, `bar=`, `scale=`: override the automatic layout;
  171. - `axis=`: the axis text, e.g. `'Δ<i>G</i><sub>sol</sub>\n(kcal/mol)'`;
  172. - `enthalpies=`: a ΔH table;
  173. - `bars='lines'|'bonds'`: draw bars and connectors as Line-tool objects (as the SOP text
  174. says) or as bonds (as in the group's reference figure; connectors then follow a dragged
  175. bar in ChemDraw).
  176. - **Structures.** `ep.structure(label, draw_fn_or_smiles, side=None, dx=, dy=, number=True,
  177. auto=True)` puts TSs above and intermediates below, each with its bold number. It then
  178. moves the structure further away or sideways until it touches nothing.
  179. - **`save()` prints:**
  180. - the RDKit self-check of the structures;
  181. - an **energy check**: the CDXML is read back, and every bar must be at the right height
  182. for its value, every value text must sit at its bar, and the heights must follow the scale
  183. pair by pair. Numbers that belong to no bar are listed.
  184. - `OVERLAP:` warnings for any text, curve or structure that touches something else. Fix
  185. them before showing the figure:
  186. - a curve or its text: `at=` and `curve=` on that step;
  187. - a bar's value or number: `side=`;
  188. - a structure: `dx=`/`dy=` or `side=` in `ep.structure`;
  189. - otherwise: `x=` to move the step to another slot, or a wider `span=`.
  190. - `NOTE:` lines saying which points had their texts mirrored because their bars are close.
  191. - the table of values as drawn. Show it to the user next to the figure.
  192. - **Your own additions.** `ep.add(lambda s, pts: ...)` draws extra items on the profile
  193. (`pts[label]` gives `x0`, `x1`, `xc`, `y`, `top`, `bottom`). These are kept on every
  194. `save()` and checked for overlaps. Editing the Scene returned by `build()` does not work,
  195. because `save()` builds again.
  196. - **A set of figures** (one per method in a benchmark, or main text plus SI): build the
  197. profiles, then call `common_sides(ep1, ep2, ...)` before saving them, so that every figure
  198. mirrors the same points. Their heights still differ with the energies.
  199. - cdxkit draws new profiles. To put new numbers into a hand-finished ChemDraw profile, edit
  200. that file instead of redrawing it (see styles/liu-group.md).
  201. Workflow that works well: write one small script per figure, one function per row or panel;
  202. render; look at the PNG; adjust coordinates; repeat. Keep the script with the figure so it can
  203. be regenerated after the user's comments.
  204. ## 4. Limitations (tell the user when relevant)
  205. - The PNG is cdxkit's own rendering, made to match ChemDraw; ChemDraw's own rendering can
  206. differ slightly (label clipping, double-bond offsets, kerning). Use `cdxkit.chemdraw` to get
  207. a ChemDraw-rendered PNG when exact appearance matters.
  208. - Labels ChemDraw knows (`TIPSO`, `MeO2C`, `BocHN`) are read by ChemDraw as chemistry. Labels
  209. that cdxkit cannot split into units the way ChemDraw does (primes such as `Ar′`, `[Fe]`,
  210. `Bpin`, formulas such as `C5H11`, unknown abbreviations) are stored as shown and marked
  211. `LabelDisplay="Right"`, so ChemDraw draws them as written but may mark them as uninterpreted.
  212. - Reactions are drawn as graphics, not as ChemDraw reaction objects.
  213. - Molecules do not avoid each other automatically; positions come from your coordinates
  214. (use the returned boxes). Only `EnergyProfile.structure` searches for a free place.
  215. - Not drawn by cdxkit: radical dots, orbitals, perspective rings with gaps at crossing bonds,
  216. insets drawn at another scale, several panels in one energy profile. Add them in ChemDraw.
README.md · README · 227 lines
  1. # chemdraw-figure-kit (cdxkit)
  2. Draw chemistry figures in Python and get **editable ChemDraw files** (CDXML) plus a matching
  3. **600 dpi PNG**: reaction schemes, rows of literature reactions, catalytic cycles,
  4. organometallic π complexes, and reaction energy profiles drawn to scale from DFT energies, in
  5. ChemDraw's ACS Document 1996 style.
  6. The repository is also a **Claude Code skill**. With it installed, an AI assistant can draw
  7. publication figures on request, follow a named house style, and hand back files that open
  8. and stay editable in ChemDraw.
  9. | cdxkit's own PNG | the same CDXML opened and rendered by ChemDraw 23 |
  10. |---|---|
  11. | ![rows](examples/out/02_literature_rows.png) | ![rows in ChemDraw](examples/out/chemdraw/02_literature_rows_chemdraw.png) |
  12. | ![cycle](examples/out/03_catalytic_cycle.png) | ![cycle in ChemDraw](examples/out/chemdraw/03_catalytic_cycle_chemdraw.png) |
  13. | ![energy profile](examples/out/04_energy_profile.png) | ![energy profile in ChemDraw](examples/out/chemdraw/04_energy_profile_chemdraw.png) |
  14. ## Why
  15. ChemDraw is the standard for chemistry figures, but drawing by hand is slow to repeat. When a
  16. reviewer asks you to change the colour of every removed hydrogen, re-centre twenty rows, or
  17. redraw a catalytic cycle, every figure has to be edited one at a time. cdxkit keeps each figure
  18. as a short script:
  19. - **Reproducible:** change one line and regenerate every figure in the same style.
  20. - **Still ChemDraw:** the output is a real CDXML document, with ACS 1996 settings, molecules
  21. as fragments, and arrows as ChemDraw arrow objects, so the final touches can be made in
  22. ChemDraw.
  23. - **Checked:** each CDXML is read back with RDKit and compared with what was drawn. Problems that
  24. only show in the picture, such as a bond hidden behind two labels, are reported as warnings.
  25. For energy profiles, every bar height and every printed value is read back from the file and
  26. checked against the input energies. On Windows, the file can also be opened by ChemDraw
  27. itself through COM automation.
  28. ## Features
  29. - Molecules from SMILES, laid out by RDKit and scaled to 14.4 pt bonds. You can rotate, mirror
  30. and add abbreviation labels (`Ar`, `TIPSO`, `[Fe]`). Wedge and hash bonds come from the
  31. stereochemistry.
  32. - Hand-drawn fragments for organometallics. Metal–π coordination is a dashed line to a bond
  33. midpoint, written as a ChemDraw multi-centre attachment. Explicit H atoms are placed in the
  34. open direction, and an allene centre can be shown as a dot.
  35. - Text with sub/superscripts, italics and bold, using ChemDraw's label and caption
  36. conventions.
  37. - Arrow types: straight, half-headed, equilibrium, dashed, arc, and curved *hook* arrows
  38. tangent to a catalytic cycle.
  39. - Boxes, filled tiles, brackets, row separators, and named colours, with your own colours
  40. added to the CDXML colour table.
  41. - Layout helpers:
  42. - place a molecule by the edge of its ink box;
  43. - draw an arrow long enough for its conditions;
  44. - stack rows (`RowFigure`) and centre each one;
  45. - move or measure any part of a scene.
  46. - Reaction energy profiles (`cdxkit.energy`):
  47. - layout: one to three pathways drawn to scale (10 kcal/mol = 1 in), branches from shared
  48. intermediates, mirrored labels for close bars, scale breaks;
  49. - annotations: curved lines and arrows for reagents entering and products leaving;
  50. - structures: TS structures above the profile and intermediates below, each moved to a
  51. free place automatically;
  52. - checks: the energies are read from a CSV table, written back out of the CDXML and compared,
  53. and overlaps are reported.
  54. - Three style guides (`styles/`): plain ACS; *literature-rows* for thesis or review
  55. background figures; and *liu-group* for computational figures, i.e. energy profiles and TS
  56. structures, following the Liu group's figure SOPs.
  57. ## Install
  58. ```bash
  59. git clone https://github.com/Ruiqi-Ding-chem/chemdraw-figure-kit.git
  60. cd chemdraw-figure-kit
  61. pip install -r requirements.txt # numpy, matplotlib, rdkit
  62. python examples/02_literature_rows.py # writes examples/out/02_literature_rows.cdxml + .png
  63. ```
  64. ## Quick start
  65. ```python
  66. from cdxkit import Scene
  67. from cdxkit import layout as L
  68. s = Scene() # ACS 1996: Arial 10 pt, bonds 14.4 pt
  69. m, box = L.place(s, 'C=CCC', 10, 60) # 1-butene; m = {atom index: (x, y)}
  70. fp = s.add_atom_label(*L.metal_above(m[0], m[1]), 'Fp<sup>+</sup>')
  71. L.eta2(s, fp, m[0], m[1]) # dashed eta-2 bond to the C=C midpoint
  72. L.add_h(s, m[2], deg=-90, color='red') # the allylic H that is removed
  73. x = L.arrow_with_conditions(s, box[2] + 14, 60, above=['Et<sub>3</sub>N'])
  74. L.place(s, '*CC=CC', x + 12, 60, labels={0: 'Fp'})
  75. L.save(s, 'out/fp_allyl') # out/fp_allyl.cdxml + .png, self-check PASS
  76. ```
  77. Units are points (1/72 in) with y pointing down, as in CDXML. Angles are degrees
  78. counter-clockwise on paper. Draw at print size, and the figure comes out at ACS sizes when
  79. inserted at 100 %.
  80. More in `examples/`:
  81. - `01_quickstart.py`: a single scheme;
  82. - `02_literature_rows.py`: one literature reaction per row;
  83. - `03_catalytic_cycle.py`: a catalytic cycle with hook arrows;
  84. - `04_energy_profile.py`: an energy profile with two competing pathways (made-up energies);
  85. - `SKILL.md`: a compact API table.
  86. ## Reaction energy profiles
  87. ```python
  88. from cdxkit.energy import EnergyProfile, load_energies
  89. E = load_energies('energies.csv', column='M06/def2-TZVP') # label, one column per method
  90. ep = EnergyProfile(energies=E)
  91. ep.path(['1', 'TS1', ('2', None, dict(add='R<sub>2</sub>C=O')), '3', 'TS3a', '4a'])
  92. ep.path(['3', 'TS3b', '4b']) # a branch: starts at the shared point 3
  93. ep.structure('TS1', draw_ts1) # your drawing function, placed above TS1
  94. ep.save('out/profile')
  95. ```
  96. The layout follows the group SOP described in [`styles/liu-group.md`](styles/liu-group.md):
  97. - Format: one column (4.5 in) up to 5 structures, two columns (10 in) for 6–10. Bars are
  98. 0.6 in.
  99. - Labels: one-decimal values with a true minus sign above each bar, and bold compound numbers
  100. below.
  101. - Pathways in black, dark blue and dark red, joined by thin solid connectors.
  102. `save()` reads the CDXML back and reports `energy check PASS` only if every bar sits at the
  103. height of its value and every value text sits next to its bar. It also lists numbers that
  104. belong to no bar and texts or curves that overlap, and prints the table of values as drawn.
  105. Bars can be ChemDraw Bold lines (default) or bold bonds (`bars='bonds'`), so that connectors
  106. follow when a bar is dragged in ChemDraw.
  107. ## Catalytic cycles
  108. ```python
  109. from cdxkit.cycle import Cycle
  110. cyc = Cycle(s, cx=200, cy=140, r=58) # clockwise
  111. cyc.arc(62, 16) # arc arrow between two intermediates
  112. cyc.hook(54, 'in', 'base') # reagent joins the cycle tangentially
  113. cyc.hook(34, 'out', 'BH<sup>+</sup>') # by-product leaves
  114. cyc.hook(148, 'in', draw_substrate) # a structure instead of a caption
  115. ```
  116. Each hook runs on a small circle that touches the cycle from outside, so it merges with the
  117. cycle's direction instead of meeting it at an angle.
  118. ## Open in ChemDraw (optional, Windows)
  119. ```bash
  120. python -m cdxkit.chemdraw examples/out/03_catalytic_cycle.cdxml cycle_chemdraw.png cycle.cdx
  121. ```
  122. This uses ChemDraw's COM automation to open the CDXML and save it again (`.png`, `.cdx`,
  123. `.emf`). It refuses to run while ChemDraw is already open, so unsaved work cannot be touched,
  124. and it only quits a ChemDraw instance it started itself.
  125. ## Use as a Claude Code skill
  126. ```powershell
  127. ./install_skill.ps1 # Windows: copies the kit to ~/.claude/skills/chemdraw-figures
  128. ```
  129. ```bash
  130. ./install_skill.sh # macOS / Linux
  131. ```
  132. Then ask Claude Code for a figure, e.g. *"redraw this scheme in ChemDraw"*, *"draw the
  133. catalytic cycle in the literature-rows style"* or *"make the energy profile from energies.csv
  134. in the liu-group style"*. The skill (`SKILL.md`) tells the assistant three things:
  135. - **Choose a style first.** Use a style only when you name it; otherwise ask which one you
  136. want.
  137. - **Follow rules that hold in every style.** Draw structures as the source does (no flipped
  138. products), copy numbers exactly and say what kind they are, and keep one drawing convention
  139. within a figure.
  140. - **Check the result.** Render, look at the PNG, run the CDXML self-check, and hand back both
  141. files.
  142. ## Styles
  143. - [`styles/acs-plain.md`](styles/acs-plain.md): ChemDraw ACS Document 1996, black only.
  144. - [`styles/literature-rows.md`](styles/literature-rows.md): background figures for a thesis or
  145. review chapter.
  146. - One literature reaction per row, with a bold "Author, year" title.
  147. - A small palette where each colour has one meaning: removed H and new bond, labels,
  148. catalyst box, side paths.
  149. - Curved in/out arrows on catalytic cycles.
  150. - [`styles/liu-group.md`](styles/liu-group.md): computational figures, following the figure,
  151. ChemDraw and reaction-energy-profile SOPs of the Liu group (Peng Liu, University of
  152. Pittsburgh).
  153. - Dashed bonds only for bonds forming or breaking in a TS; dative bonds in grey.
  154. - Energy profiles drawn to scale, with pathway colours by rank.
  155. - Sizing for a single reduction of the whole figure in Word.
  156. Add your own by writing a new `styles/<name>.md`.
  157. ## Tests
  158. ```bash
  159. python tests/test_examples.py # or: python -m pytest tests
  160. ```
  161. The tests do the following:
  162. - build every example, write it, and read it back with RDKit;
  163. - read the energy-profile example back for bar heights and values;
  164. - check energy rounding (half away from zero, never "−0.0") and CSV reading;
  165. - check that one label given two energies is rejected;
  166. - check that a value changed in the file is caught by the read-back;
  167. - check that labels left of their bond are stored in ChemDraw's typed order.
  168. With ChemDraw installed (Windows), `CDXKIT_CHEMDRAW=1 python tests/test_examples.py` also lets
  169. ChemDraw open, save and reopen a sheet of labels, and requires the same picture each time.
  170. ## Limitations
  171. - The PNG is cdxkit's own rendering, made to match ChemDraw. Label clipping, double-bond
  172. offsets and kerning differ slightly from ChemDraw's output (compare the gallery above).
  173. - Labels are written as they should appear (`TIPSO` left of its bond). In the CDXML they are
  174. stored in ChemDraw's typed order (`OTIPS`), so ChemDraw shows the same label when it opens
  175. the file and after it saves it. Labels cdxkit cannot split into units the way ChemDraw does
  176. (`Ar′`, `[Fe]`, `Bpin`, `C5H11`, unknown abbreviations) are stored as shown and marked to be
  177. drawn as stored; ChemDraw may mark these as uninterpreted.
  178. - Reactions are drawn as graphics, not ChemDraw reaction objects. Molecules do not avoid each
  179. other automatically; only structures on an energy profile look for a free place.
  180. - Not drawn: radical dots, orbitals, perspective rings with gaps at crossing bonds, insets at a
  181. different scale. Add them in ChemDraw.
  182. - cdxkit draws new energy profiles. To put new numbers into a hand-finished ChemDraw profile,
  183. edit that file instead.
  184. ## License
  185. MIT, © 2026 Ruiqi Ding. Developed with Claude Code.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.