Skip to content

Commit

Permalink
✨ Add the enhancement option
Browse files Browse the repository at this point in the history
  • Loading branch information
@LazyYuuki
LazyYuuki committed Sep 19, 2024
1 parent 597d176 commit d2a4d18
Show file tree
Hide file tree
Showing 6 changed files with 548 additions and 1 deletion.
6 changes: 5 additions & 1 deletion src/SUMMARY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,4 +14,8 @@
- [Video Component](./chapter1/web-components/video.md)
- [References Component](./chapter1/web-components/references.md)
- [Pushing the changes you made to Github](./chapter1/push-to-github.md)
- [Optional enhancement]()
- [Chapter 2: Optional enhancement](./chapter2/index.md)
- [Make your report into multiple pages](./chapter2/pages.md)
- [Working with Chart.js](./chapter2/chart.md)
- [Working with Mermaid.js](./chapter2/diagram.md)
- [Working with 3D Render](./chapter2/3d-render.md)
76 changes: 76 additions & 0 deletions src/chapter2/3d-render.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# Working with 3D Render

To render 3D object such as your CAD in the format of `.stl` file, we will use the [Three.js](https://threejs.org/) library. It is a very cool library that allows you to do mind-blowing graphic stuff in the browser. However, it is very out-of-scope for our purpose, so we have helped written a component script so you can just simply use it with minimal configuration to display your `.stl` file.

To use the 3D render component, we need to import the following into our `index.html` file.

```html
<head>
...

<script type="importmap">
{
"imports": {
"three": "https://cdn.jsdelivr.net/npm/[email protected]/build/three.module.js",
"three/addons/": "https://cdn.jsdelivr.net/npm/[email protected]/examples/jsm/"
}
}
</script>
<script type="module"
src="https://cdn.jsdelivr.net/npm/@shoelace-style/[email protected]/cdn/shoelace-autoloader.js"></script>

...

<script type="module" src="./render.js"></script>
</body>
```

It is a bit more complicated than other module because of the `three.js` library. It is important that you make sure the import is in the order above for `three.js` to work properly. Don't forget the `type="module"` when importing the `render.js` file as it is necessary for the script to work properly.

To use the component, you just simply have to create a `<div>` with the `id` value that you want:

```html
<div id="render1"></div>
```

Then, in the `render.js` file call the `createRender` function accordingly as shown.

```js
createRender(
"render1",
400,
[0, -1, 0],
[0.05, 0.05, 0.05],
[-Math.PI / 2, 0, 0],
false,
"../assets/benchy.stl",
);
```

It will render your `.stl` file in the specified `<div>`.

Now, let take a loot at what each of the arguments means, and how you can use them:

```js
function createRender(
id,
height,
position,
scale,
rotation,
enableAxes,
stlFilePath,
) {
```
- `id`: is the id you gave to the `div` element that you want to render your `.stl` to.
- `height`: is the height in pixel of the view box of your object. You can adjust the width by modifying the `div` width directly
- `position`: the position of your object in 3D space, in the following order [x , y , z]
- `scale`: same as position but for scaling, you will have to experiment to see what scale would work for you as some stl can be very big, and some can be very small.
- `rotation`: same as position and scale, but for the rotation angle of your object. It uses Euler angle. As a rule of thumb you should use `Math.PI / 2` as trial value because it equals to a rotation of 90 degree.
- `enableAxes`: whether you want to enable the X Y Z axis for debugging purposes or not.
- `stlFilePath`: this is the path to your `.stl` file. Do note that Github has file size limitations to what you can upload there, so if your CAD is just too big in memory size, maybe it would be better if you upload it to some other storage method such as Google Drive or Dropbox and then provide the url to that `stl` file here. Otherwise, just put your `stl` file into the `assets` folder, and write the correct path to that `stl` file here.
Rendering 3D can be quite intensive on some more underpowered devices, so try to only use this component to show things that would highlight your effort instead of dumping every single CAD that you have here. Because remember, the user would need to download all of you CAD before they can view them, so it doesn't make sense to make user download 1GB worth of CAD to view it for only 5 seconds.
In another word, use this component prudently and responsibly.
254 changes: 254 additions & 0 deletions src/chapter2/chart.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,254 @@
# Working with Chart.js

To make the process of creating chart simple and streamline, we will utilize [Chart.js](https://www.chartjs.org/docs/latest/) library. If you open up the `index.html` in the `chart` folder. You should see the following:

```html
<!DOCTYPE html>
<html lang="en">

<head>
.....

<!-- You can add what components you want to include here -->
<link rel="stylesheet" href="../index.css">
<link rel="stylesheet" href="../components/scroll-to-top/scroll-to-top.css">
<script src="../components/scroll-to-top/scroll-to-top.js"></script>

<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>

<!-- -->
</head>

<body>
<div class="content">
<sl-button href="../">Back</sl-button>

<h2 id="pie-doughtnut">1. Pie and Doughnut Chart</h2>
<div style="display: flex; justify-content: space-around;">
<div style="width: 45%;">
<canvas id="pie-chart"></canvas>
</div>
<div style="width: 45%;">
<canvas id="doughnut-chart"></canvas>
</div>
</div>

<br />
<h2 id="bar">2. Bar Chart</h2>
<div>
<canvas id="bar-chart"></canvas>
</div>

<br />
<h2 id="line">3. Line Chart</h2>
<div>
<canvas id="line-chart"></canvas>
</div>

<br />
<h2 id="scatter">4. Scatter Chart</h2>
<div>
<canvas id="scatter-chart"></canvas>
</div>

<sl-button class="scroll-to-top" variant="primary" size="medium" circle onclick="scrollToTop()">
<sl-icon name="arrow-up" label="Settings"></sl-icon>
</sl-button>

<script src="./chart.js"></script>
</body>

</html>
```

We import the `Chart.js` library by simply adding the following line:

```html
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
```

Now, we will create elements where we will draw the chart using Javascript later. To do that we use the following syntax:

```html
<div>
<canvas id="something-chart></canvas>
</div>
```
The `id` can be anything you want, but remember that it should be unique to each graph because that is how you differentiate them in the Javascript code section later.
You would also notice that differnt from our usual way of import, we need to import the `chart.js` file at the bottom of the `<body>` element:
```html
...
<sl-button class="scroll-to-top" variant="primary" size="medium" circle onclick="scrollToTop()">
<sl-icon name="arrow-up" label="Settings"></sl-icon>
</sl-button>
<script src="./chart.js"></script>
</body>
```
This is because Javascript cannot grab an element if it has not been initialized yet. As we will see in the subsequent code in `chart.js`, it needs to know that `pie-chart` exist, before it can grab that elements, so we cannot declare the import before the declaration of the elements. In general, people tend to import Javascript code at the bottom of the body for this reason, but for organisation purpose, we would like to put thing related together closer to each other unless we have no other choice.
Now open up the `chart.js` file. Take this sample code:
```js
const PieCtx = document.getElementById("pie-chart");
const DoughnutCtx = document.getElementById("doughnut-chart");
const PieData = {
labels: ["Red", "Blue", "Yellow"],
datasets: [
{
label: "My First Dataset",
data: [300, 50, 100],
backgroundColor: [
"rgb(255, 99, 132)",
"rgb(54, 162, 235)",
"rgb(255, 205, 86)",
],
hoverOffset: 4,
},
],
};
new Chart(PieCtx, {
type: "pie",
data: PieData,
});
new Chart(DoughnutCtx, {
type: "doughnut",
data: PieData,
});
```
The `PieCtx` constant holds the container which is the `<canvas id="pie-chart"></canvas>`, this is how we tell Javascript which `<canvas>` to draw what which is why we need the `id` to be unique.
Then we define what the data we want the chart to render. We will go indepth into this in a bit.
Finally, we will render this chart. To do this the syntax is:
```js
new Chart(ctx, {
type: "pie",
data: PieData
})
```
Where `ctx` stands for context, in another word, the `<canvas>` element that you grab. `type` refer to chart type you want to render, and finally the data you want the chart to render.
Now, we will go more indepth regarding the configuration of each graph, you could also learn more directly from [here](https://www.chartjs.org/docs/latest/charts/)
## 1. Pie and Doughnut Chart
```js
const PieData = {
labels: ["Red", "Blue", "Yellow"],
datasets: [
{
label: "My First Dataset",
data: [300, 50, 100],
backgroundColor: [
"rgb(255, 99, 132)",
"rgb(54, 162, 235)",
"rgb(255, 205, 86)",
],
hoverOffset: 4,
},
],
};
```
Let break down what each of this fields means:
- `labels`: the labels for your data, it should match with the number of data you have
- `datasets`: the content of chart
- `label`: is the label for this particular dataset, it will make more sense in subsequent charts
- `data`: this is where you specify your data in an array, make sure you have same number of data as the labels
- `backgroundColor`: this is for aesthetic purpose, you can use any standard css color syntax. If you don't want any color variation, just delete this portion.
- `hoverOffset`: is just show how far should the offset from the center of the chart where the tooltip show when you hover over the chart
## 2. Bar Chart
```js
const BarData = {
labels: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul"],
datasets: [
{
label: "My First Dataset",
data: [65, 59, 80, 81, 56, 55, 40],
borderWidth: 1,
},
{
label: "My Second Dataset",
data: [23, 40, 67, 20, 79, 30, 80],
borderWidth: 1,
},
],
};
```
We can see that the `datasets` now have 2 set of data: `My First Dataset` and `My Second Dataset`.
This is why datasets is declared as an array of object. Because you can show one or more dataset on the same chart space.
`borderWidth` just specify how thick the border of the bar you want them to be.
## 3. Line Chart
```js
const LineData = {
labels: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul"],
datasets: [
{
label: "My First Dataset",
data: [65, 59, 80, 81, 56, 55, 40],
fill: false,
tension: 0.1,
},
{
label: "My Second Dataset",
data: [23, 40, 67, 20, 79, 30, 80],
tension: 0.1,
},
],
};
```
- `fill`: whether you want the area under the line to be filled or not.
- `tension`: whether you want to smooth out the turn at each data point. At 0, it will just be straightline connect at each data point.
## 4. Scatter Chart
```js
const ScatterData = {
datasets: [
{
label: "Scatter Dataset",
data: [
{
x: 2,
y: 4,
},
{
x: 3,
y: 2,
},
{
x: 4,
y: 5,
},
{
x: 0.5,
y: 5.5,
},
],
backgroundColor: "rgb(255, 99, 132)",
},
],
};
```
Each data point in a scatter chart requires an `x` and `y` coordinates. We suggest that if you need to use a scatter graph, you should create a simple Python script maybe with the help of ChatGPT to convert all of your data to the format above and then just copy paste accordingly.
39 changes: 39 additions & 0 deletions src/chapter2/diagram.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Working with Mermaid.js

[Mermaid.js](https://mermaid.js.org) can be said to be the defacto standard when it comes to creating diagram using Domain Specific Language. In fact, if you have ever seen diagram being render on Github repository before, it is all thanks to mermaid.js.

This section won't be teaching you how to create diagram but only how to allow you to render those diagram. To learn how to create this beautiful diagram, you can read their [document](https://mermaid.js.org/syntax/flowchart.html) or use their [Live Editor](https://mermaid.live) instead.

If you open the `diagram` folder, you should be able to see 3 files:

- `index.html`
- `diagram.js`
- `svg-pan-zoom.min.js`

In the `index.html` file, we import 2 things:

```html
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.min.js"></script>
<script src="svg-pan-zoom.min.js"></script>
```

The former is to import `mermaid.js`, the latter is to import the `svg-pan-zoom` library. Since this library have a bit of a problem being loaded from the CDN, we instead download it down to a file locally and name it as `svg-pan-zoom.min.js`.

The purpose of the `svg-pan-zoom` is allowing us to zoom in and out and pan around our diagram, which will allow you to draw bigger diagram without worrying that it is not readable. This is the main advantage over just taking a picture of your diagram. You don't have to use it if you don't want to, but it surely would make your report more interactive.

To render a mermaid chart, you just have to declare the `<pre>` element and give it the mermaid class. It will automatically be rendered.

Similar to the chart, we need to import `diagram.js` file at the bottom of the `<body>` element.

```html
...

<sl-button class="scroll-to-top" variant="primary" size="medium" circle onclick="scrollToTop()">
<sl-icon name="arrow-up" label="Settings"></sl-icon>
</sl-button>

<script src="./diagram.js"></script>
</body>
```

We don't actually need to know what is happening in the `diagram.js` file as it is only glue code to help with stitching the `svg-pan-zoom` with `mermaid.js` library. Just remember to include all of this file if you decide to use mermaid.js to draw your diagram.
15 changes: 15 additions & 0 deletions src/chapter2/index.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Chapter 2: Optional enhancement

In this chapter, we will be learning how to use more advanced components to enhance your web report. We will learn how to:

1. Split your report into seperate sections and tabs for ease of readability.
2. Import components and code as you need them.
3. Use Chart.js to create simple charts.
4. Make interactive diagram with Mermaid.js.
5. Render 3D object such as your CAD using Three.js.

To view what the template for the optional enhancement, you can visit the link below:

[Demo](https://edic-nus.github.io/advanced/)

The source code is available [here](https://github.com/edic-nus/advanced)
Loading

0 comments on commit d2a4d18

Please sign in to comment.