Merge pull request #50 from kiruma524/tutorial

Tutorial

Author: altavir

docs/tutorial.md

@@ -1,6 +1,6 @@
-#Tutorial
+# Tutorial
 
-###The main goal of this tutorial is to show all capabilities of ... (this part will be supplemented)
+#### The main goal of this tutorial is to show all capabilities of ... (this part will be supplemented)
 
 The simple visualization can be made with function `main`. (this part will be supplemented as well)
 ```kotlin
@@ -28,19 +28,19 @@ fun main(){
     }
 }
 ```
-##Solids properties
+## Solids properties
 **We will analyze which basic properties solids have using `box` solid.**
 
-Basic properties:
+*Basic properties:*
 1. `opacity` - It is set in `float`. It takes on values from 0 to 1, which represent percents of solid opacity. It's initial value is 1.
 2. `color` - It can be specified as `Int`, `String`, or as three `Ubytes`, which represent color in `rgb`. Elementally, the solid will have `green` color.
-3. `rotation` - it's the point, around which the solid will be rotated. Initially, the value is `Point3D(0, 0, 0)`
-4. position, which is given by values `x`, `y`, `z`. Initial values are `x = 0`, `y = 0`, `z = 0`
+3. `rotation` - it's the point, around which the solid will be rotated. Initially, the value is `Point3D(0, 0, 0)`. Changing `x` coordinate of the point, you make pivot around `x axis`. The same for other coordinates: changing `y` - pivot around `y axis`, changing `z` - pivot around `z axis`.
+4. position, which is given by values `x`, `y`, `z`. Initial values are `x = 0`, `y = 0`, `z = 0`. The coordinate system is Cartesian. It's elemental position is this - vertical `y` axis and horizontal `Oxz` plane.
 
 Let's see how properties are set in solids.
 The `small box` will have elemental values of properties. If you will not set properties, it will have the same `position`, `color`, `rotation`, and `opacity` values.
 
-***You can see that `box` take four values. Later, we will discuss what they are doing in more detail. Now, it does not really matter.***
+***You can see that `box` take four values. Later, we will discuss what they do in more detail. Now, it does not really matter.***
 ```kotlin
 box(10, 10, 10, name = "small box"){
    x = 0
@@ -65,7 +65,6 @@ box(40, 40, 40, name = "big box"){
 }
 ```
 ![](../docs/images/big-rotated-box.png)
-
 If we compare these boxes, we will see all differences. 
 
 Here is the function `main` with both boxes.
@@ -107,52 +106,90 @@ fun main(){
 ![](../docs/images/two-boxes-1.png)
 ![](../docs/images/two-boxes-2.png)
 
-###Basic Solids
+***There is plenty of other properties, especially of those, which you can create by yourself. Here we mention just small part.***
 
+## Basic Solids
 Now, let's see which solids can be visualized:
-1) PolyLine
-2) Box
-   ```kotlin
+### 1) PolyLine
+### 2) Box
+
+First thing which has to be mentioned is that `box` takes four values: `box(x, y, z, name)`
+* `x` - x-axis length of the `box`
+* `y` - y-axis length of the `box`
+* `z` - z-axis length of the `box`
+
+These values have `Float` type. *`x`, `y`, and `z` are necessary values, which cannot be ignored. You have to set them.*
+
+* `name` - `box`'es identifier with `String` type. *It's an optional value, but without it you won't be able to control solid.*
+
+Let's create just usual `box` with equal ribs.
+
+```kotlin
    box(50, 50, 50, name = "box") {
-        x = 0
-        y = 0
-        z = 0
         color("pink")
    }
-   ```
+```
    ![](../docs/images/box.png)
+
+Now, let's make `box` with bigger `y` value.
    ```kotlin
-   box(10, 25, 10, name = "high_box") {
-        x = 0
-        y = 0
-        z = 0
+   box(10, 25, 10, name = "high box") {
         color("black")
    }
    ```
+As you can see, only rib of `y-axis` differs from other ribs.
+
    ![](../docs/images/high-box.png)
+
+For final trial, let's create `box` with bigger `x` value.
 
    ```kotlin
-   box(65, 40, 40, name = "wide_box") {
+   box(65, 40, 40, name = "wide box") {
         x = 0
         y = 0
         z = 0
         color("black")
    }
    ```
+Predictably, only `x-axis` rib bigger than other ribs. 
+
    ![](../docs/images/wide-box.png)
 
-3) Sphere
+### 3) Sphere
+
+It takes in two values: `radius`, and `name`. 
+Actually, `name` is general value for all solids, so do not wonder, since all solids need their own identifier.
+
+As for `radius`, it has `Float` type, and, as you can guess, it sets radius of the sphere, which will be created.
    ```kotlin
    sphere(50, name = "sphere") {
         x = 0
         y = 0
         z = 0
+        opacity = 0.9
         color("blue")
    }
    ```
    ![](../docs/images/sphere.png)
-4) Hexagon
-   ```kotlin
+
+### 4) Hexagon
+
+It is solid which has six edges. It is set by eight values: `node1`,..., `node8`. They all have `Point3D` type, so they are just points, vertices.
+
+*Six edges are these:* 
+1) Edge with vertices `node1`, `node4`, `node3`, `node2`
+2) Edge with vertices `node1`, `node2`, `node6`, `node5`
+3) Edge with vertices `node2`, `node3`, `node7`, `node6`
+4) Edge with vertices `node4`, `node8`, `node7`, `node3`
+5) Edge with vertices `node1`, `node5`, `node8`, `node4`
+6) Edge with vertices `node8`, `node5`, `node6`, `node7`
+
+![](../docs/images/scheme.png)
+
+As hexagon takes in specific points, we understand that this solid cannot be moved, it fixed in space, and it can't make pivots.
+
+Let's make classic parallelepiped.
+```kotlin
    hexagon(
         Point3D(25, 30, 25),
         Point3D(35, 30, 25),
@@ -162,11 +199,14 @@ Now, let's see which solids can be visualized:
         Point3D(40, 18, 20),
         Point3D(40, 18, 10),
         Point3D(30, 18, 10),
-        name = "classic_hexagon"){
+        name = "classic hexagon"){
         color("green")
    }
-   ```
+```
    ![](../docs/images/classic-hexagon.png)
+
+Now, let's make a custom hexagon.
+
    ```kotlin
    hexagon(
         Point3D(5, 30, 5),
@@ -182,28 +222,112 @@ Now, let's see which solids can be visualized:
    }
    ```
    ![](../docs/images/custom-hexagon.png)
-5) Cone
-   ```kotlin
+### 3) Cone
+It takes in six values: `bottomRadius`, `height`, `upperRadius`, `startAngle`, `angle`, and `name`. 
+
+Obviously, `bottomRadius` is responsible for radius of a bottom base, and `height` sets height of a cone along the `z-axis`.
+
+As it takes such values as `upperRadius`, `startAngle`, `angle`, `cone` can build not only usual cones, but also cone segments. Initially, `upperRadius` will have `0.0` value, `startAngle` - `0f`, `angle` - `PI2`, so if you don't set them, you'll get just a simple cone. 
+
+Setting `upperRadius`, you make a frustum cone, since it sets a radius of the upper base of a cone. Set `startAngle`, and `angle` let to cut off segments by planes perpendicular to the base. `startAngle` - an angle, starting with which segment will be left, `angle` - an angle of cone, which will be set from `startAngle`. 
+
+Let's build a classic cone:
+```kotlin
    cone(60, 80, name = "cone") {
-         x = 0
-         y = 0
-         z = 0
          color("beige")
    }
    ```
    ![](../docs/images/cone-1.png)
    ![](../docs/images/cone-2.png)
-6) Cone Surface
-   ```kotlin
-   coneSurface(60, 50, 30, 10, 100, name = "cone_surface") {
-        x = 0
-        y = 0
-        z = 0
+
+First of all, we have to try to build a frustum cone:
+```kotlin
+cone(60, 80, name = "cone") {
+   color(0u, 40u, 0u)
+}
+```
+![](../docs/images/frustum-cone.png)
+
+Now, we need to make a try to build a cone segment:
+
+```kotlin
+cone(60, 80, angle = PI, name = "cone") {
+   color(0u, 0u, 200u)
+}
+```
+![](../docs/images/cone-segment-1.png)
+![](../docs/images/cone-segment-2.png)
+
+Finally, the segment of frustum cone is left for a try:
+```kotlin
+cone(60, 100, 20, PI*3/4, angle = PI/3, name = "cone") {
+   color(190u, 0u, 0u)
+}
+```
+![](../docs/images/frustum-cone-segment.png)
+
+### 4) Cone Surface
+This solid is set by seven values:`bottomOuterRadius`, `bottomInnerRadius`, `height`, `topOuterRadius`, `topInnerRadius`, `startAngle`, and `angle`.
+
+In addition to `height`, `startAngle`, and `angle`, which work as they work in `cone`, there are some new values.
+`bottomOuterRadius`, and `bottomInnerRadius` set properties of the bottom circle, `topOuterRadius`, `topInnerRadius` - of the upper circle. They have no initial value, so that means they have to be set.
+
+Generally, `cone`, and `coneSurface` buildings work in the same way, it's possible to make `coneSurface`'s fragments as in `cone`
+
+Let's build usual cone surface with almost all properties set:
+```kotlin
+   coneSurface(60, 50, 30, 10, 100, name = "cone surface") {
         color("red")
         rotation = Point3D(2, 50, -9)
    }
    ```
-   ![](../docs/images/cone-surface-1.png)
-   ![](../docs/images/cone-surface-2.png)
-7) Extruded
+![](../docs/images/cone-surface-1.png)
+![](../docs/images/cone-surface-2.png)
+
+Now, let's create a cone surface and set all it's properties:
+
+```kotlin
+coneSurface(30, 25, 10, 10, 8,0f, pi*3/4, name = "cone surface") {
+   color("fuchsia")
+   rotation = Point3D(2, 50, -9)
+}
+```
+![](../docs/images/cone-surface-fragment.png)
+![](../docs/images/cone-surface-fragment-2.png)
+
+### 5) Cylinder
+
+This solid is set by `radius`, and `height`. As you can see by accepting values, there's no option of building fragments of cylinders.
+
+Here's a demonstration of a cylinder:
+
+```kotlin
+cylinder(40, 100, "cylinder"){
+   rotation = Point3D(40, 0, 0)
+   color("indigo")
+}
+```
+![](../docs/images/cylinder-1.png)
+![](../docs/images/cylinder-2.png)
+### 6) Tube
+
+`tube` takes in `radius`, `height`, `innerRadius`, `startAngle`, `angle`, and `name`. *All values are familiar from `cone`, and `coneSurface` solids.*
+
+Here is an example of classic tube:
+```kotlin
+tube(50, 40, 20, name = "usual tube"){
+   opacity = 0.4
+}                    
+```
+![](../docs/images/tube.png)
+
+This is an example of tube fragment:
+
+```kotlin
+tube(50, 40, 20, 0f, PI, name = "fragmented tube"){    
+   color("white")
+}
+```
+![](../docs/images/tube-fragment.png)
+### 7) Extruded