search

PMKS-Web / PMKSWeb

An educational web-based tool designed for comprehensive 2D linkage analysis developed at WPI (Worcester Polytechnic Institute)
https://pmksplus.com
5 stars 3 forks source link

readme

Planar Mechanism Kinematic Simulator Plus (PMKS+)

Github Hero

PMKS+ (Planar Mechanism Kinematic Simulator Plus) is an educational web-based tool designed for comprehensive 2D linkage analysis. It offers an interactive platform for users to rapidly create, edit, and analyze planar linkages. Along with performing kinematic and force analysis, PMKS+ allows for easy sharing of linkages with peers or teaching staff.

Built with a strong emphasis on the four core principles of education, flexibility, collaboration, and accessibility, PMKS+ aims to provide a user-friendly experience that aids learning and promotes understanding of complex concepts in a simplified manner.

Key Features

Interactive Linkage Creation & Editing: Easily create and modify planar linkages with a user-friendly interface.

Verification

A Matlab Script (SixBarVerification.m) was used to verify the Analysis and the v,p,a obtained from this Mechanism . The values were compared and a test script was created to continue verifying similar Mechanisims.

Development Setup

For development, we recommend using WebStorm, a powerful IDE ideal for JavaScript development. It is free for students and faculty members with a .edu email. You can download it here.

Steps to Set Up the Development Environment

  1. Download & Install WebStorm: Visit the WebStorm site and download the software. Remember to register with your .edu email to get it for free.

  2. Clone the Repository: Using WebStorm, clone the PMKS+ repository to your local machine.

  3. Install Node JS: https://nodejs.org/en/download

  4. Install Dependencies: The necessary dependencies should automatically install when the repository is cloned. If any dependencies are missing, you can run npm install to add them.

  5. Set Up Run Configurations: Create two run configurations in WebStorm:

    • First Configuration: A npm configuration that runs 'npm start'.
    • Second Configuration: A JavaScript Debug configuration with the URL set to http://localhost:4200. This allows you to run a locally hosted test site on port 4200 and use breakpoints and the debugger to identify errors.

  6. Angular DevTools: We recommend using the Angular DevTools extension for your browser (available for both Chrome and Firefox). This tool provides additional functionality for debugging and optimizing your Angular applications.

With these steps, you should have a fully functional development environment for PMKS+. Happy coding!

Coding Guidelines and Workflow

We encourage high code quality and strive for clean, readable, and maintainable code. Here are some general practices we follow:

  1. Code Purposefully: Code should be written in a simple, obvious style with descriptive variable and function names. Avoid commenting code to explain how it works; instead, code should be written in a way that is inherently understandable. Use comments to explain why—to describe high-level behavior and its importance.

  2. Keep Code Short: Try to keep classes under 200 lines of code if possible and functions short. This prevents the emergence of "god" classes that can make the codebase difficult to maintain.

  3. Good OOP Practices: Follow principles like SOLID, DRY, and prefer composition over inheritance. If complex relationships seem necessary, reach out first so we can discuss the best approach.

  4. Follow Programming Conventions:

    • File names should always be dash-delimited, with dots being used to denote the “type” of the file. For example: currency-converter.pipe.ts1
    • All service classes should end with the term Service. For example: HeroService1
    • Selectors for your components should always be dash-delimited, like files, and contain the appropriate app prefix. For example: app-hero-list
    • The name of a component class should end with Component. For example: HeroListComponent
    • The name of a directive class should end with Directive. For example: HighlightDirective
    • The name of a module class should end with Module. For example: AppModule2
    • The name of a pipe class should be in PascalCase and end with Pipe. For example: CurrencyConverterPipe2
    • For more details, check out Angular's offical coding style guide.

While the codebase may not always perfectly adhere to these conventions, the aim is to continually improve the codebase to meet these standards.

Workflow

We follow an agile scrum-style workflow, using an issue tracker (Kanban board) in our GitHub organization here.

The process is as follows:

  1. Create a fork for each issue you work on.
  2. Once you've resolved an issue in your fork, submit a pull request to the main branch.

Please note, the main branch has a CI/CD workflow setup that will update the production website, so nothing should be pushed directly to the main branch!

The commits to the main branch will get reflected on app.pmksplus.com

All other branches will get published to https://[BRANCHNAME]--pmks.netlify.app (For example https://staging--pmks.netlify.app)

Landing Page: https://pmksplus.com

This project was generated with Angular CLI version 13.2.5.

Development server

Run ng serve for a dev server. Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files.

Code scaffolding

Run ng generate component component-name to generate a new component. You can also use ng generate directive|pipe|service|class|guard|interface|enum|module.

Build

Run ng build to build the project. The build artifacts will be stored in the dist/ directory.

Additional Help Resoruces

To get more help on the Angular CLI use ng help or go check out the Angular CLI Overview and Command Reference page.

Usage Instructions

PMKS+ features an intuitive interface that allows you to create, edit, and analyze 2D linkages efficiently.

Application Interface

The PMKS+ interface consists of a full-screen grid with a toolbar at the top and an animation bar at the bottom.

Using the Tool

  1. Synthesis: Use the synthesis tab to automatically generate a linkage based on a desired position for one of the links.

  2. Edit: When the edit tab is open, you can modify the properties of the selected object (highlighted in amber color).

  3. Analysis: The analysis panel allows you to view kinematics and force analysis graphs for the selected object.

  4. Settings: The settings panel enables you to modify overall mechanism settings, such as units, input speed, enabling gravity, as well as visual settings like mechanism size and grid line visibility.

  5. Animation Control: Use the animation bar to control the playback of the linkage simulation. You can set the playback speed, play or pause the animation, reset the animation to T=0, and seek through the simulation using the scrubber.

  6. File Management: Use the toolbar buttons to create a new project, load a project, access the Linkage Library, download the current project, and generate a shareable URL for the current project.

Remember, only one tab can be open at a time for each group (left and right), and the linkage can only be modified when the animation is paused and reset to T=0.

Licensing

PMKS+ is licensed under the MIT License, a popular, permissive open-source license. The full license text is included in the LICENSE file in this repository.

Contact

For any queries, you can reach out to the development team at gr-pmksplus@wpi.edu.

Acknowledgements

PMKS+ is based on PMKS, developed by Prof. Matthew I. Campbell, Professor, Mechanical Engineering, Oregon State University.

Contributors

Faculty