README.md

Cuiping.js

English | 简体中文

Table of Contents

• Brief
• Experience
  • Basic function
  • Monaco Editor function
  • About saving images
  • App configuration
  • (advanced) URL params
• Usage
  • Only use backend
  • Rendering configuration
  • Using the Vue component in the browser
• Contribution
  • Welcome PR!
  • Development plan
  • Build the project
  • Test the project
  • Commit your changes
  • Happy coding!
• Thanks
• License

Brief

Render the chemical formula of SVG format in the browser, using the accurate Cuiping formula syntax.

Experience

You can try the demo at icelava.top.

Basic function

• Try to input Cuiping formula and view rendered results in real time
• Save the formulas you tried to browser
• Modify the rendering configuration at any time
• Check some preset examples and edit them
• Hover over the rendering result to zoom, copy Cuiping formula or download SVG images

Monaco Editor function

• Support syntax highlighting of Cuiping Formula
• Support auto-completion of Refs and Attributes
• Support going to definition of Refs (Ctrl-Click or Right Click > Go To Definition)
• Support marking Groups (Ctrl-M or Right Click > Toggle Group Mark)

About saving image

• Hover on the output and click SVG in the pop-up toolbar to download vector graph.
• To get non-vector images (e.g. for PPT), turn on the Use Image option in configuration, then you can copy or save the image by right-clicking them.

App configuration

Options	Type	Description
useMonacoEditor	boolean	Whether to use Monaco Editor
useImage	boolean	Whether to render to PNG instead of SVG
imageScale	number	Scale of the image, only when useImage is on. Larger scale makes the image clearer

(advanced) URL params

Param	Description
debug	Enable debug
nohistory	Do not display the history
noexamples	Do not display examples

Usage

Only use backend (including parsing and rendering)

1. Use your familiar package manager to install the core package cuiping.

   $ pnpm i cuiping
   $ yarn add cuiping
   $ npm i cuiping

2. Use TypeScript.

   import { render } from 'cuiping'
   
   const molecule = getMolecule()      // Assume to obtain Cuiping formula from user input.
   
   const data = render(molecule, {
       onError: err => {
           console.warn(err)           // Handling errors.
       },
       renderer: 'svg',                // Only SVG rendering mode is supported currently.
       rendererOptions: { /*...*/ }    // Render configuration, see below.
   })
   
   if (data) {                         // SVG rendering results will be obtained if there is no error.
       showSvg(data.svg)               // Show SVG to the user.
   }

Rendering configuration

Options	Type	Description
unitLen	integer	Unit length
paddingX	integer	X padding
paddingY	integer	Y padding
displayBonds	boolean	Whether to display bonds
bondGap	integer	Gap between double/triple bonds
lineBaseColor	string	Base color of lines
textBaseColor	string	Base color of text
displayBackground	boolean	Whether to display background
backgroundColor	string	Background color
halfFontSize	integer	Half font size
halfTextBoxWidth	integer	Half width of text boxes
halfTextBoxHeight	integer	Half height of text boxes
displayTextBox	boolean	Whether to display text boxes

Using the Vue component in the browser

See component document.

Contribution

Welcome PR!

We use ESLint to unify code style and run checks by Husky and GitHub Action.

Development plan

The development plan of this project can be found on Notion.

Build the project

1. Clone the code repository in your familiar way.

   $ git clone https://github.com/ForkKILLET/Cuiping.js
   $ gh repo clone ForkKILLET/Cuiping.js

2. Use pnpm to install dependencies.

   $ pnpm i

3. Start the main building job.

   $ pnpm build

   Or start package-level building job separately, using workspace.

   $ pnpm -F {cuiping,cuiping-component,cuiping-frontend}

   Or cd into package directories and start package-level building job.

   $ cd {backend,component,frontend}
   $ pnpm build

Test the project

1. Test the backend only.

   $ cd backend
   $ pnpm build:run

   You may set environment variable to enable debug.

   $ DEBUG=1 pnpm build:run

   Run testcases: (How to add testcases is shown below)

   $ pnpm build:test

2. Test all functions in the frontend. (recommended)
   Development mode:

   $ cd frontend
   $ pnpm dev

   Production mode:

   $ cd frontend
   $ pnpm build
   $ pnpm preview

3. You may add ?debug URL param to enable debug. When debug is on, the program will:
   • Print debug-level logs
   • Expose debug functions to window (printStruct and showMoleculeSequence)
   • Add a TestCase button to the toolbar of the component. You may click it to copy the testcase.

Commit your changes

Please use ng style for commit message. You may refer to git log.

Happy coding!

Thanks

License

This project is open source under MIT license.