From 184504990c136ab79320cdf238732c619d6ea23d Mon Sep 17 00:00:00 2001
From: kurokida <kurokid@lit.kyushu-u.ac.jp>
Date: Wed, 27 May 2020 16:37:07 +0900
Subject: [PATCH] add explanations about demos

---
 .gitignore                          |  1 +
 demos/lines.html                    |  2 +-
 demos/movingCircles.html            | 17 ++++---
 demos/movingCircles_frames.html     | 70 ++++++++++++++++----------
 demos/twoImagesWithSOAinFrames.html |  2 +-
 demos/twoSoundsWithSOA.html         |  2 +-
 docs/demo_explanation.md            | 77 ++++++++++++++++++++++++++++-
 docs/index.md                       |  4 +-
 jspsych-psychophysics.js            |  2 +-
 9 files changed, 136 insertions(+), 41 deletions(-)
diff --git a/.gitignore b/.gitignore
index 11cba1c..88ea98d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,4 @@ stepFuncをミスしたやつ.js
 demos/test0518.html
 demos/test0518b.html
 jspsych-psychophysics03.js
+calc_velocityを変更しようとしてやめたやつ.js
diff --git a/demos/lines.html b/demos/lines.html
index 5db7890..f2b3644 100644
--- a/demos/lines.html
+++ b/demos/lines.html
@@ -9,7 +9,7 @@
 <script>
     // This file demonstrates how to present lines.
     // There are two ways to define a line.
-    // Note: You can not specify the angle and positions at the same time.
+    // Note: You can not specify both the angle and positions for the same object.
     
     // The line_object1 defines a line using the angle and line_length.
     var line_object1 = {
diff --git a/demos/movingCircles.html b/demos/movingCircles.html
index 6388460..81445f3 100644
--- a/demos/movingCircles.html
+++ b/demos/movingCircles.html
@@ -9,9 +9,9 @@
 <script>
     // This file demonstrates how to present moving circles.
     // There are three ways to define motion.
-    // Note: You can not specify the speed, location, and time at the same time.
+    // Note: You can not specify the speed, distance, and time at the same time.
     
-    // The circle_object1 defines motion using the location and time.
+    // The circle_object1 defines motion using the distance and time.
     var circle_object1 = {
         obj_type: 'circle',
         startX: 200, // location in the canvas
@@ -26,7 +26,8 @@
         motion_end_time: 4000,
     }
 
-    // The circle_object2 defines motion using the location and speed.
+    // The circle_object2 defines motion using the distance and speed.
+    // This blue circle moves from right to left (600-200=400 pixel) at 80 pixel/sec, so it takes 5 seconds.
     var circle_object2 = {
         obj_type: 'circle',
         startX: 600, // location in the canvas
@@ -36,8 +37,8 @@
         radius: 50,
         line_color: 'blue', // You can use the HTML color name instead of the HEX color.
         fill_color: 'blue',
-        horiz_pix_frame: -3, // The circle moves from right to left.
-        vert_pix_frame: 0,
+        horiz_pix_sec: -80, // The circle moves from right to left.
+        vert_pix_sec: 0,
         show_start_time: 500, // ms after the start of the trial
         motion_start_time: 1000,
     }
@@ -50,11 +51,11 @@
         radius: 50,
         line_color: 'red', // You can use the HTML color name instead of the HEX color.
         fill_color: 'red',
-        horiz_pix_frame: -3, // The circle moves from right to left.
-        vert_pix_frame: 2,
+        horiz_pix_sec: -80, // The circle moves from right to left.
+        vert_pix_sec: 60,
         show_start_time: 500, // ms after the start of the trial
         motion_start_time: 1000,
-        motion_end_time: 4000,
+        motion_end_time: 6000,
     }
 
     var trial = {
diff --git a/demos/movingCircles_frames.html b/demos/movingCircles_frames.html
index c33bb05..eff5065 100644
--- a/demos/movingCircles_frames.html
+++ b/demos/movingCircles_frames.html
@@ -7,29 +7,13 @@
 </head>
 <body></body>
 <script>
-    // This file demonstrates how to present moving circles.
-    // Note: You can not specify the speed, location, and time at the same time.
+    // This file demonstrates how to present moving circles in frames.
+    // Note: You can not specify the speed, distance, and time at the same time.
     
-    // The circle_object1 defines motion using the location and time.
-    // In this case, you have to define the time in ms not in frames.
+    // The circle_object1 defines motion using the time and speed.
+    // If you defined the time in frames, you have to also define the speed in frames.
+    // The `is_frame` property should be true.
     var circle_object1 = {
-        obj_type: 'circle',
-        startX: 200, // location in the canvas
-        startY: 400,
-        endX: 600,
-        endY: 400,
-        radius: 50,
-        line_color: 'black', // You can use the HTML color name instead of the HEX color.
-        fill_color: 'black',
-        show_start_time: 500, // ms after the start of the trial
-        motion_start_time: 1000,
-        motion_end_time: 4000,
-    }
-
-    // The circle_object2 defines motion using the location and speed.
-    // In this case, you can define the time both in ms and frames.
-    // But, if you defined the time in frames, you have to also define the speed in frames.
-    var circle_object2 = {
         obj_type: 'circle',
         startX: 'center', // location in the canvas
         startY: 'center',
@@ -37,17 +21,51 @@
         line_color: 'blue', // You can use the HTML color name instead of the HEX color.
         fill_color: 'blue',
         show_start_frame: 60, // frames after the start of the trial
-        motion_start_frame: 100,
-        motion_end_frame: 200,
-        show_end_frame: 250,
+        motion_start_frame: 120,
+        motion_end_frame: 240,
+        show_end_frame: 300,
         is_frame: true, // required
-        horiz_pix_frame: 3, // speed in frames
+        horiz_pix_frame: -5, // speed in frames
         vert_pix_frame: 0, // The circle does not move vertically.
     }
 
+    // The circle_object2 defines motion using the distance and speed.
+    var circle_object2 = {
+        obj_type: 'circle',
+        startX: 600, // location in the canvas
+        startY: 400,
+        endX: 200,
+        endY: 400,
+        radius: 50,
+        line_color: 'red', // You can use the HTML color name instead of the HEX color.
+        fill_color: 'red',
+        horiz_pix_frame: -5, // The circle moves from right to left.
+        vert_pix_frame: 3,
+        show_start_frame: 60, // ms after the start of the trial
+        motion_start_frame: 120,
+        is_frame: true, // required
+    }
+
+    // If you specify the distance and time, the velocity can be calculated automatically.
+    // But, in this case, you have to define the time in milliseconds not in frames.
+    var circle_object3 = {
+        obj_type: 'circle',
+        startX: 200, // location in the canvas
+        startY: 400,
+        endX: 600,
+        endY: 400,
+        radius: 50,
+        line_color: 'black', // You can use the HTML color name instead of the HEX color.
+        fill_color: 'black',
+        show_start_time: 500, // milliseconds!
+        motion_start_time: 1000, // milliseconds!
+        motion_end_time: 3000, // milliseconds!
+        show_end_time: 3500 // milliseconds!
+    }
+
     var trial = {
         type: 'psychophysics',
-        stimuli: [circle_object1, circle_object2],
+        stimuli: [circle_object1, circle_object2, circle_object3],
     }
 
     jsPsych.init({
diff --git a/demos/twoImagesWithSOAinFrames.html b/demos/twoImagesWithSOAinFrames.html
index e7303a7..f63b398 100644
--- a/demos/twoImagesWithSOAinFrames.html
+++ b/demos/twoImagesWithSOAinFrames.html
@@ -7,7 +7,7 @@
 </head>
 <body></body>
 <script>
-    // This file demonstrates how to present two images with 500-ms SOA
+    // This file demonstrates how to present two images with 1000-ms SOA
 
     images = [ // All the images used in this demo
         './img/scissors.png',
diff --git a/demos/twoSoundsWithSOA.html b/demos/twoSoundsWithSOA.html
index 7d4ad71..6e2ec43 100644
--- a/demos/twoSoundsWithSOA.html
+++ b/demos/twoSoundsWithSOA.html
@@ -9,7 +9,7 @@
 <body></body>
 <script>
     // This file demonstrates how to present sounds with 1000-ms SOA.
-    // This demo must be uploaded in a web-server to run.
+    // Note that the experimental files (html, js, and audio) must be uploaded in a web-server to run.
 
     sounds = [ // All the sound files used in this demo
         './sound/tone100ms.wav'
diff --git a/docs/demo_explanation.md b/docs/demo_explanation.md
index e9867a3..dbd82d0 100644
--- a/docs/demo_explanation.md
+++ b/docs/demo_explanation.md
@@ -8,10 +8,83 @@ The cross object can be used to present a fixation point. In this demo, moving t
 
 ## [draw_part_of_image.html](https://www.hes.kyushu-u.ac.jp/~kurokid/jspsychophysics/demos/draw_part_of_image.html)
 
-This file demonstrates how to use the drawFunc with the image object. You need not to use the drawFunc when you present images normally. But if you want to modify the images, for example, if you want to present a part of the image, the drawFunc is useful.
+This file demonstrates how to use the `drawFunc` with the image object. You need not to use the drawFunc when you present intact images. But if you want to modify the images, for example, if you want to present a part of the image, the drawFunc is useful.
 
 ## [draw_two_images_repeatedly.html](https://www.hes.kyushu-u.ac.jp/~kurokid/jspsychophysics/demos/draw_two_images_repeatedly.html)
 
 This file demonstrates how to present two images repeatedly until a participant responds to them. This demonstration can be applied to the study on like change blindness.
 
-You can also make the participants respond using a mouse instead of a keyboard using the **response_type** property. See, demos/localize-circle.html.
+## [elapsed_time_frame.html](https://www.hes.kyushu-u.ac.jp/~kurokid/jspsychophysics/demos/elapsed_time_frame.html)
+
+This file demonstrates how to use the `stepFunc` which is called by the requestAnimationFrame method. The elapsed time after begging of a trial is presented both in milliseconds and in frames.
+
+## [lines.html](https://www.hes.kyushu-u.ac.jp/~kurokid/jspsychophysics/demos/lines.html)
+
+This file demonstrates how to present lines. There are two ways to define a line; one is to specify the angle and line_length, the other is to specify the start and end positions of the line. Note: You can not specify both the angle and positions for the same object.
+
+## [localize-circle.html](https://www.hes.kyushu-u.ac.jp/~kurokid/jspsychophysics/demos/localize-circle.html)
+
+This file demonstrates how to respond using a mouse, and how to use the `response_type` and `response_start_time` property.
+    
+## [manual_drawFunc_gradation.html](https://www.hes.kyushu-u.ac.jp/~kurokid/jspsychophysics/demos/manual_drawFunc_gradation.html)
+
+Using the `drawFunc`, gradation from white to black is presented.
+
+## movingCircles.html(https://www.hes.kyushu-u.ac.jp/~kurokid/jspsychophysics/demos/movingCircles.html)
+
+This file demonstrates how to present moving circles. There are three ways to define motion. 
+
+1. Using the distance and time. 
+2. Using the distance and speed.
+3. Using the time and speed.
+    
+Note: You can not specify the speed, distance, and time at the same time.
+    
+## movingCircles_frame.html(https://www.hes.kyushu-u.ac.jp/~kurokid/jspsychophysics/demos/movingCircles_frame.html)
+
+The show_start(end)_frame is used instead of the show_start(end)_time.
+Also, the motion_start(end)_frame is used instead of the motion_start(end)_time.
+
+CAUTION: If you define motion using the distance and time, you have to specify the time in milliseconds not in frames.
+
+## randomizedImages.html(https://www.hes.kyushu-u.ac.jp/~kurokid/jspsychophysics/demos/randomizedImages.html)
+
+This file demonstrates how to present a fixation point and an image in the center of the display in a randomized order. 
+
+## rectangles.html(https://www.hes.kyushu-u.ac.jp/~kurokid/jspsychophysics/demos/rectangles.html)
+
+This file demonstrates how to present (moving) rectangles.
+
+## stepFunc.html(https://www.hes.kyushu-u.ac.jp/~kurokid/jspsychophysics/demos/stepFunc.html)
+
+This file demonstrates how to use the stepFunc which is called by the requestAnimationFrame method, and excuted synchronized with the refresh of the display.
+
+You can directly access the canvas (of which the context) using the stepFunc. You can draw complex visual stimuli.
+
+## text-rect-circle.html(https://www.hes.kyushu-u.ac.jp/~kurokid/jspsychophysics/demos/text-rect-circle.html)
+
+This file demonstrates how to present a message(text), a rect, and a circle with SOAs
+
+## texts.html(https://www.hes.kyushu-u.ac.jp/~kurokid/jspsychophysics/demos/texts.html)
+
+The 'Hello world!' demonstration. You can start a new line using the '\n'. Texts can be moved as the same as rectangles.
+
+## tutorial.html(https://www.hes.kyushu-u.ac.jp/~kurokid/jspsychophysics/demos/tutorial.html)
+
+The detailed tutorial is written at [the top page](http://jspsychophysics.hes.kyushu-u.ac.jp/)
+
+## twoImagesWithSOA.html(https://www.hes.kyushu-u.ac.jp/~kurokid/jspsychophysics/demos/twoImagesWithSOA.html)
+
+This file demonstrates how to present two images with the 500-ms SOA
+
+## twoImagesWithSOAinFrames(https://www.hes.kyushu-u.ac.jp/~kurokid/jspsychophysics/demos/twoImagesWithSOAinFrames.html)
+
+This file is nearly same as the twoImagesWithSOA.html except for that the display durations are specified in frames not in ms.
+
+The first image is presented for 5 frames (about 83 ms in a 60 Hz monitor), and the second image is presented for 20 frames (about 333 ms in a 60 Hz monitor) with a 60-frame SOA.
+
+## twoSoundsWithSOA.html(https://www.hes.kyushu-u.ac.jp/~kurokid/jspsychophysics/demos/twoSoundsWithSOA.html)
+
+This file demonstrates how to present two sounds with a 1000-ms SOA.
+
+Note that the experimental files (html, js, and audio) must be uploaded in a web-server to run.
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
index 5463a60..547bad6 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -14,6 +14,8 @@ This is the brief explanation how to use the plugin. Please refer to [the parame
 This figure illustrates a trial flow to be made by this tutorial.
 ![tutorial](./images/tutorial.png)
 
+You can see [the sample of this tutorial.](https://www.hes.kyushu-u.ac.jp/~kurokid/jspsychophysics/demos/tutorial.html)
+
 ### 1. Download the plugin file
 [Please download the latest files from GitHub.](https://github.com/kurokida/jspsych-psychophysics/releases)
 The package includes the comaptible [jsPsych](http://www.jspsych.org/) (de Leeuw, 2015), and released under [the MIT license](https://opensource.org/licenses/MIT).
@@ -86,8 +88,8 @@ Note that if you use image and audio files in a trial, please preload them using
 - [Two white squares are presented asynchronously without the jspsych-psychophysics plugin](http://www.psycho.hes.kyushu-u.ac.jp/jspsych-6.0.5-multi-objects/examples/native_two_rectangles.html)
 - [Two white squares are presented asynchronously with the jspsych-psychophysics plugin](http://www.psycho.hes.kyushu-u.ac.jp/jspsych-6.0.5-multi-objects/examples/pp_two_rectangles.html)
 - [A white square and a sin-wave sound are presented asynchronously without the jspsych-psychophysics plugin (SOA=500ms)](http://www.psycho.hes.kyushu-u.ac.jp/jspsych-6.0.5-multi-objects/examples/native_rect_sound.html)
+- [A sophisticated program proposed by a reviewer in the 0ms-SOA no-plugin condition.](http://www.psycho.hes.kyushu-u.ac.jp/jspsych-6.0.5-multi-objects/examples/native_rect_sound_soa0.html)A white square and a sin-wave sound are presented at the same time (SOA=0) without the jspsych-psychophysics plugin. In this program, a white rectangle image is presented using the the `prompt` parameter of the audio-keyboard-response plugin, and the `use_webaudio` is specified as true.
 - [A white square and a sin-wave sound are presented asynchronously with the jspsych-psychophysics plugin](http://www.psycho.hes.kyushu-u.ac.jp/jspsych-6.0.5-multi-objects/examples/pp_rect_sound.html)
-- [A white square and a sin-wave sound are presented asynchronously without the jspsych-psychophysics plugin (SOA=0)](http://www.psycho.hes.kyushu-u.ac.jp/jspsych-6.0.5-multi-objects/examples/native_rect_sound_soa0.html)
 
 
 Copyright (c) 2019 Daiichiro Kuroki  
diff --git a/jspsych-psychophysics.js b/jspsych-psychophysics.js
index d0af39b..16ffe50 100755
--- a/jspsych-psychophysics.js
+++ b/jspsych-psychophysics.js
@@ -281,7 +281,7 @@ jsPsych.plugins["psychophysics"] = (function() {
       if (typeof stim.motion_start_frame === 'undefined') stim.motion_start_frame = stim.show_start_frame; // Motion will start at the same frame as it is displayed.
       if (typeof stim.motion_end_frame === 'undefined') stim.motion_end_frame = null;
       
-      // calculate the velocity using the distance and the time.
+      // calculate the velocity (pix/sec) using the distance and the time.
       // If the pix_sec is specified, the calc_velocity returns the intact pix_sec.
       // If the pix_frame is specified, the calc_velocity returns an undefined.
       stim.horiz_pix_sec = calc_velocity('horiz', stim);
