Cuiping.js

English | 简体中文

Table of Contents

• Brief
• Experience
• 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!
• License

Brief

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

Experience

You can experience the demo at icelava.top:

• 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 copy Cuiping formula or download SVG images

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
halfFontSize	integer	Half font size
halfTextBoxWidth	integer	Half width of text boxes
halfTextBoxHeight	integer	Half height of text boxes
displayTextBox	boolean	Whether to show 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

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 set cuipingDebug in localStorage to enable debug.

   localStorage.cuipingDebug = 1

Commit your changes

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

Happy coding!

License

This project is open source under MIT license.