Linking MKI3D stages into webs of stages

URL links in the  MKI3D editor 

In the recent version of MKI3D you can place URL links in your designed stages that can be followed when the stage is browsed in  MKI3D TRAVEL.

The link symbol in the MKI3D editor looks like that:

Like the selected and bookmarked points, the link symbols are displayed in the current cursor's  color, and are always facing the observer.

URL submenu

There is a new position 'U' on the main menu:

This is for creating and manipulating URL links. At present, the URL submenu looks like that:

You can add a new empty link at the cursor position by pressing the 'A' key on this submenu.

(There is a minimal distance required between any two links positions.)

The edit ('E'), cut ('X') and paste ('V') actions are performed on the link at cursor position. 

There is a new option 'U' at the cursor submenu, the moves the cursor to the position of the nearest link.

Edit URL submenu

The editing of link is done in the following submenu:

The textfields on Edit URL  submenu

There are three input text fields for: LABEL, OPENER, and URL.

LABEL may be any any text. It is prominently displayed in the  MKI3D TRAVEL, when the user is offered to follow the link.

OPENER and URL are used to construct the actual URL of the page that is opened by the link.
If OPENER and URL are full (i.e. not relative) URLs, then they are simply concatenated.
The result should be a legal full URL that can be opened by the browser.

For example if:

• OPENER is 'https://mki1967.github.io/mki3d/mki3d_www/mki3d.html?input=', and
• URL is 'https://mki1967.github.io/mki3d-data/data/web/stage1.mki3d',

then the actual URL to be opened is:


https://mki1967.github.io/mki3d/mki3d_www/mki3d.html?input=https://mki1967.github.io/mki3d-data/data/web/stage1.mki3d

If OPENER or URL is a relative URL, then it is first extended to a full URL
("actual opener URL" or "actual input URL", respectively).
Then the concatenation of "actual opener URL" with "actual input URL"  is the URL to be opened by the browser.

The construction is made with the URL() constructor ,
where a different "base URLs" are used for OPENER and URL
( "opener URL base" and  "input URL base", respectively).

Computing "actual input URL" from URL

The "actual input URL" is made from the URL with the "input URL base",
if the URL is a relative URL. 

If the the MKI3D editor or  in the  MKI3D TRAVEL were opened with the parameter '?input=' ,
then the "input URL base" is  the URL of the loaded stage.
(The value of the parameter  '?input=' may also be an relative URL. In such case, the "input URL base" is the URL of the document.referrer - the URL of the page from which it is opened.)

Thus the relative URL links in the stage are assumed to have the same base as the stage itself. (This enables desingnig and testing  of local webs with the http://localhost server and then publishing them e.g. by pushing on public static pages such as GitHub Pages.)

Computing "actual opener URL" from OPENER

If the OPENER is empty the the "actual opener URL" is also empty.

In  MKI3D TRAVEL and in MKI3D editor  the "opener URL base" is taken from
window.location.href, thus the OPENER from the link is assumed to have the same base as the current opener of the stage.

Note that

• https://mki1967.github.io/mki3d/mki3d_www/mki3d.html and
• https://mki1967.github.io/mki3d/mki3d_www/travel.html

have the same url base. 
Thus, if you are working in the editor open from the URL: 

 https://mki1967.github.io/mki3d/mki3d_www/mki3d.html 

and if the link has:

• OPENER : 'travel.html?input=', and
• URL : 'https://mki1967.github.io/mki3d-data/data/web/stage1.mki3d',

then the actual URL to be opened is:

https://mki1967.github.io/mki3d/mki3d_www/travel.html?input=https://mki1967.github.io/mki3d-data/data/web/stage1.mki3d

On the other hand, if the editor were open from URL:

http://localhost:8000/mki3d/mki3d_www/mki3d.html

then the actual URL to be opened by such link would be:

http://localhost:8000/mki3d/mki3d_www/travel.html?input=https://mki1967.github.io/mki3d-data/data/web/stage1.mki3d

This is useful if you want to work with applications served by the http://localhost server
from your local clones of MKI3D repo. 
(You may follow the hints from README.md  of the mki3d-data repo.)
Probably, you would like to have the links with the short relative URLs, like:

• OPENER: 'travel.html?input=', and
• URL: 'stage1.mki3d'

Remainig options of URL Edit submenu

The 'Tab' key on the submenu lets you test what would be opened with the  current values

of OPENER and URL.

Note that the the actual URL opened by the link with relative URLs depends on how the editor was started.

The 'X' and 'V' keys let you cut the link and then paste it in the cursor positions. This is useful if you want to remove the link, or to make many copies or similar links.

Stages in the  MKI3D editor vs. the stages in the MKI3D TRAVEL.

Stages browsed in MKI3D TRAVEL the  are designed in the  MKI3D editor .

The entry point to the stage in the MKI3D TRAVEL is where the cursor was left in the  MKI3D editor . 

The observer is aligned with X,Y,Z axes looking into positive Z direction. 

To see the orientation in  MKI3D editor , you should see the cursor like that:

The scaling from MKI3D editor is not applied in  MKI3D TRAVEL. To see the size of the stage in MKI3D editor set CURSOR STEP to 1 on the Inputs Page ('QI').

Don't forget to set the proper light direction ('QDL') . It is used in the  MKI3D TRAVEL.

INDEX OF MKI3D WEB

I have just created a HTML page on GitHb Pages that is intended to contain a list of links that are entries to the web of MKI3D stages. The address of the page is:  https://mki3d.github.io/mki3d-web-index/

If you want to submit  such link to your stage the please read and follow the simple instructions in
README.md. (I short: you just have to open new issue containing the URL that opens your stage in MKI3D TRAVEL.)

URLs for Opening MKI3D with Loaded Input Data

The new version ( v0.20 ) of MKI3D PWA can be used to display your mki3d designs in the browser.

You can create links on your pages that can open the MKI3D editor with loaded content.
The link consists of the address of the application  'https://mki1967.github.io/mki3d/mki3d_www/mki3d.html'  with a  parameter 'input' in its query string, which is an URL of the mki3d data file.

Here are some examples of links to the stages of mki3dgame directly on the GitHub:

• https://mki1967.github.io/mki3d/mki3d_www/mki3d.html?input=https://raw.githubusercontent.com/mki1967/mki3dgame/master/assets/stages/MKI3D-stage-1.mki3d
• https://mki1967.github.io/mki3d/mki3d_www/mki3d.html?input=https://raw.githubusercontent.com/mki1967/mki3dgame/master/assets/stages/stage9.mki3d
• https://mki1967.github.io/mki3d/mki3d_www/mki3d.html?input=https://raw.githubusercontent.com/mki1967/mki3dgame/master/assets/stages/cubic-stage.mki3d

If the 'input' parameter is releative URL, the MKI3D tries to append the URL base of its 'document.referrer'. ('document.referrer' is the page that contains the opening link.)
You can also specify the parameter 'base' that overrides the URL base of  'document.referrer'.

The following page contains examples of the use cases:

https://mki1967.github.io/mki3d/docs/examples/mki3d-data/test-url.html


(Note that you may need to close and reload MKI3D on-line twice or more  to have the progressive app updated to the new version.)

Tutorial Post 20: Using IndexedDB.

Mki3d can now (since version 0.11) store your designs in IndexedDB.
IndexedDB is an internal local database managed by the related browser.
The 'IndexedDB Menu' in mki3d can be invoked by a key sequence 'QB'.

On this menu you can:

• press the key 'A' to store the current design in the database, or
• press the key 'I' to start 'Inspecting IDB' sub-menu for inspecting the database.

Thus, to store your design, you only have to press the key sequence 'QBA'.
The entry is stored with the following attributes: its name and creation date.
You do not need to change the name, since the database can contain many entries with the same name. It is convenient for storing many intermediate versions of your design, or if you do not want to waste your time for inventing the name or deciding where to save the data in the  file system.
(Remember that you always can set the current name on the 'Inputs Page'.)


When you inspect the database the entries are sorted by the date and you can preview the stored designs as they where visible on the screen when they where stored.
You start inspecting from the last stored one.

You can cycle through the sequence of entries backward or forward by pressig 'P' or 'N' or arrow keys.
If the database contains too many entries, you can filter them: Press 'F' to invoke the 'IDB Filters' sub-menu.

Here you can set the bounds (or single bound) of dates' range and a sub-string that the filtered entries must contain in their name.
Press 'Enter' key  to confirm or 'Esc' to cancel, and return to 'Inspecting IDB'.

While inspecting the database  you can also merge,  load, or remove the entry. Each of these actions requires confirmation:

You have to press precisely the 'Y' key to confirm. Pressing any other key cancels the action.

The last option on 'Inspecting IDB' sub-menu is 'V' that hides the menu and cursor to show you the  the preview in full display.

The IndexedDB can be convenient for rapid storing and previewing of your  designs. However, I would recommend that you still save copies of your more precious designs outside the browser: Use 'QFS' key sequence to invoke saving in the files, or by copying text from text areas.
The persistence of your data in IndexedDB may depend on the policy of the browser's producer.

Tutorial Post 19: Table of Contents.

This post is a table of contents (listing of the links to tutorial posts in increasing order) and it shall be updated with each new tutorial post.

• Tutorial Post 1: Cursor.
• Tutorial Post 2: Markers - Inserting Segments and Triangles.
• Tutorial Post 3: Data Organisation.
• Tutorial Post 4: Selected and Bookmarked Endpoints.
• Tutorial Post 5: Constructive Points.
• Tutorial Post 6: Clipping.
• Tutorial Post 7: Colors.
• Tutorial Post 8: Light.
• Tutorial Post 9: Action Modes.
• Tutorial Post 10: Inputs Page.
• Tutorial Post 11: Three-point Transformation.
• Tutorial Post 12: Regular Polygons.
• Tutorial Post 13: Cursor Jumping.
• Tutorial Post 14: Copying.
• Tutorial Post 15: Sets.
• Tutorial Post 16: Folding.
• Tutorial Post 17: Constructing regular icosahedron.
• Tutorial Post 18: Exporting as interactive HTML pages.
• Tutorial Post 19: Table of Contents. (THIS PAGE)
• Tutorial Post 20: Using IndexedDB.
• Linking MKI3D stages into webs of stages

Tutorial Post 18: Exporting as interactive HTML pages.

You can export your data to HTML page with interactive presentation of your  3D design in browsers with WebGL enabled. (Most of the modern browsers on modern devices have WebGL enabled.) You can rotate the object by mouse dragging and perform some other actions.

CLICK HERE TO SEE EXPORTED EXAMPLE.

• CLICK HERE TO SEE INDEX FILE WITH LINKS TO MORE EXPORTED EXAMPLES.
• CLICK HERE TO SEE RED-BLUE STEREOSCOPIC  EXPORTED EXAMPLES.

On the File Menu (invoked with key sequence: 'QF') you may notice the following fragment:

Notice the 'NOTE ON EXPORTING'.  The exported HTML pages contain the data, but they also need a script  mki3d_view.js to be placed in the same folder. (Any folder with a collection of exported pages needs to contain one copy of this script.)

If you press the 'E' key  on the file menu,  then mki3d starts exporting.
Exporting is similar to ordinary saving:

• If you are using mki3d as a Chrome application, then you are presented with file chooser for saving the exported page.
• If you are using mki3d in a browser, then you are presented with with a Text Save Page where the text of the exported page is placed in OUTPUT TEXT AREA, but you can also save the file with file chooser by using artificial DOWNLOAD LINK TO SAVE DATA:

The script mki3d_view.js has been updated recently to handle touch events,  so the exported designs can be interactively viewed also on the mobile devices.
Exporting of the stereoscopic views is not implemented yet. (It is a 'future work' ;-)
In the current version (since 2017.08.11)  you can also export in the red-blue stereoscopic mode.

Tutorial Post 17: Constructing regular icosahedron.

In the tutorial post about folding, we constructed  regular tetrahedron. That was easy: we aligned two equilateral triangles to the sides of another one and folded them to obtain all the needed endpoints.

Now we show how to construct regular icosahedron.


Create two copies of equilateral triangles (as it was made in the folding post) and one outline of regular pentagon. Select the enpoints of the pentagon and set constructive points for scaling the pentagon so that its side will become as long as the side of the triangles.

Invoke scaling with the key sequence  'QMS1'.

Prepare for alignment of the first triangle to the side of pentagon with a three-points transformation. The constructive points may be set as on the following figure:

Invoke the three-points transformation (key sequence 'QMT').

The same way, align the second triangle to the adjacent side of the pentagon:

Now we have to prepare the folding. Fortunately, each triangle is in a distinct set, so we can use the 'N' key to select the set and key sequence 'QSS' to select (and then also bookmark) the traingle.
The constructive points for folding should be set as follows:

After folding ('QMF') you should have something like that:

I have also set light ('QDL') to have different shades on the triangles.

Using cursor jumping, insert the remaining sides of the pentagonal pyramid:

Now we could safely remove the segments, which are the outline of the pentagon, but we will leave them to make the placement of pryramids more visible in the remaining stages.

Now select everything ('QSX'). Extract the selected vertices to a single set ('QSE') and make three copies of the pyramids:

We still need one more triangle. We could have  made one more copy at the begining, but  we are adding it now:

We have to align two of  the pyramids with the triangle using three-points transformations:

Prepare for folding of the aligned pyramids:

After folding you get something like that:

We have to append the last pyramid to our construction. Prepare for three-points transformation:

And execute the transformation. The pyramid has been placed as on the view below:

The construction is almost ready. Remainig triangles can be inserted by cursor jumping to the existing endpoints:

To make the construction balanced we can select all endpoints ('QSX') and remove all segments, which are the outlines of the pentagons ('QD4').
Then

• Move the cursor to the centroid of the selected endpoins (which is now the center of the icosahedron) with key sequence 'QMJC'.
• Set the constructive point 'A' ('QPSA')
• Using INPUTS PAGE ('QI') set cursor's X,Y,Z coordinates to zeroes.
• Set the constructive point 'B' ('QPSB')
• Move the (still selected) endpoints by the vector 'AB' (key sequence 'QMM0')

Now we have icosahedron with the center in (0,0,0).

Click to see exported to html

Tutorial Post 16: Folding.

Folding is a constructive method that makes two rotations of two disjoint sets of endpoints at once.

The inputs of folding operation are:

• four half-lines with a common initial point 'A':  'AB', 'AC', 'AD' and 'AE', and
• a point 'F' on one side of the plane 'ABC' indicating the direction of the rotations.

The lines 'AB' and 'AC' are axes of two rotations, such that the half-line 'AD' rotated by the first rotation around the line 'AB' is equal to the half-line 'AE' rotated by the second rotation around the line 'AC'.
Such rotations may not always exist. (It depends on the angles between the half-lines.)

As a simple example, let's make regular tetrahedron.
First make equilateral triangle:

• Set 3 as the NUMBER OF POLYGON VERTICES on the inputs page
• Insert outline of regular polygon ('QMI3')
• Using cursor jumping ('QCJ') to the endpoints of the outline, insert a single triangle
• Select all vertices ('QSX') and remove the segments of the outline ('QD4')

(Do not use 'QMI4', since it would insert three triangles -- the sectors of the polygon)

Then make two  copies of the triangle:

(I have also painted them with different colors.)

Then you can use two three-point transformations to align the triangles as follows (use cursor jumping ('QCJ') to set the input constructive points of the three-point transformations):

Use selecting and bookmarking to bookmark the red triangle and to select the green triangle and use cursor jumping ('QCJ') to set constructive points as follows:

Do folding ('QMF'):

The red and the green triangles have been folded around 'AC' and 'AB', respectively.
Note the point 'V' that is set by folding to denote the half-line 'AV' that is equal to the rotations of 'AD' and 'AE'.

There is still one face missing:

We can add it manually with cursor jumping to the existing endpoints:

The Folding Algorithm (formally derived here) does not use any trigonometric functions, which should have positive impact on the precision of computations.

Tutorial Post 15: Sets.

As noted in Tutorial Post on Data Organisation,  each endpoint has a set attribute. Endpoints are grouped into disjoint sets. The set attribute is just an index of the endpoint's group. There is also a 'current set index', which indicates one of the set indices.

Sets are useful for logical grouping of the endpoints.

• If the endpoints from different sets have the same position, then you can select only endpoints from the current set by pressing: 'QSS' ("ADD ENDPOINTS FROM THE CURRENT SET TO SELECTION" on Selection Menu).
• On the other hand, if you have some endpoints selected, then you can create a new set that contains only the selected endpoints, extracting them from their old sets ('QSE') ("EXTRACT THE SELECTED ENDPOINTS TO A NEW SET" on Selection Menu).
• If you created the copy of selectde endpoints ('QDC...'), then the copies of the  endpoints are placed in a new set. (The glue elements have endpoints in distinct sets.) 
• If you merge from a file ('QFM') then the sets of the merged endpoints are separate from the existing sets (while all the merged endpoints are selected and you can extract them to a single set if you wish) 

Set Menu is invoked by key sequence: 'QN'

I this menu you can change the current set and restrict visibility to the elements that have all the endpoints in (are included in)  the current set or to the elements that have at least one endpoint in (are incident to) the current set.

In the example we have copied two white segments from set 0  (with segment glues between endpoints).
The copy has been moved and painted red.
The copied endpoints have been automatically placed in new set (set 1).
The endpoints of set one have been selected with key sequence 'QSS', when the current set index was 1, and then bookmarked with 'QSB'.
Then the current set index was changed to 0 (by repeating 'QNN') and the endpitoints of set 0 (current set) have been selected ('QSS').

After pressing 'QN0'  we would see the elements included in current set:

If we pressed 'QN1' then we would see the elements incident to the current set:

(Note that now the glues are also visible.)

We can also display some statistics with 'QNP':

You may also cycle with through the available set indexes and view restrictions, by pressing just the key 'N'.

Note that the set attributes of the endpoints may change  their values while you are not watching, since mki3d tries to minimize the total number of available set indexes, by ensuring that the only index of an empty set is the maximal index. After all, the set attributes are only used to indicate the partitioning of the endpoints, and we do not want to cycle through many empty groups, nor to remember the index numeric values.

Tutorial Post 14: Copying.

We can make copies of selected elements. We will make a copy of the two red segments.

The segments already have been selected (with a key sequence: 'QSX').
We invoke Copy submenu on Data Menu (key sequence: 'QDC'):

Note that there are four kinds of copying. The term 'GLUE' denotes connection between the original and its copy. A segment's endpoint can be connected with its copy by a segment. A segment can be connected with its copy by two triangles. There is no   'GLUE'   option defined for a triangle and its copy. (In most cases you do not want glues between triangles and their copies!)

First, lets make the copy without any 'GLUE' ('QDC0').

The endpoints have been copied and placed in a new (unused) set. The old endpoints are un-selected and their copies are now selected. The copies are placed in the positions of the originals. To see that we have really made a copy, select action 'SELECTION MOVE' (key sequence: 'AS') and   move the selected copy with arrow keys.

Now, lets make copy of the first copy with the glues between the endpoints ('QDC1') and move the selected new copy with arrow key to see the results:

And finally, lets make a copy with glues between the segments ('QDC2') and move the copy:

The key sequence: 'QDC3' would make another copy with both kinds of glues.