日本語版はこちらでご覧いただけます。
This document describes how developers can embed Mini Tokyo 3D into their web page and integrate it into their applications. If you want to know how to use Mini Tokyo 3D itself, see the Mini Tokyo 3D User Guide.
Embedding Mini Tokyo 3D into a web page, or using the APIs to customize it, is very simple. Please follow the instructions in this section to get started.
Mini Tokyo 3D works on all major browsers that support ES6. Internet Explorer is not supported.
Mini Tokyo 3D uses the Mapbox service for its map tiles, so you will need a Mapbox access token to use it. It uses Map Loads for Web sessions, which are free for up to 50,000 connections per month. Follow the steps below to get an access token.
- Create a Mapbox account by entering your user information on the sign-up page.
- After logging in with your Mapbox account, click on "Tokens" in the menu at the top of the screen to view the list of access tokens. Only the "Default public token" will be displayed right after creating the account.
- Click on the "Create a token" button in the upper right corner of the screen to go to the page for creating an access token.
- In the "Token name" field, enter your web site name, app name, or any other name you want.
- The "Token scopes" should be the default setting (all public scopes should be checked).
- Enter the URL of the site where you want to install Mini Tokyo 3D in the "URL" field in the "Token restrictions" section, and then click the "Add URL" button. For the URL format, please refer to the URL restrictions. By setting this URL restriction, you can prevent other sites from using this access token for their own purposes.
- Finally, click the "Create token" button at the bottom of the screen and the newly created token will appear in the list of access tokens.
If you simply want to display a Mini Tokyo 3D map on your web page, you can edit the HTML file as follows.
First, use the jsDelivr CDN link to load the Mini Tokyo 3D style sheet and JavaScript code within the <head>
element of the HTML file.
<head>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/mini-tokyo-3d@latest/dist/mini-tokyo-3d.min.css" />
<script src="https://cdn.jsdelivr.net/npm/mini-tokyo-3d@latest/dist/mini-tokyo-3d.min.js"></script>
</head>
Within the <body>
element of the same HTML file, add an HTML element with an id
(a <div>
element in the example below), and write JavaScript code to create a Mini Tokyo 3D instance in the <script>
element. Specify the id
of the HTML element to container
of the options
object passed to the constructor. In addition, specify the Mapbox access token obtained in the above step to secrets.mapbox
.
<body>
<div id="mini-tokyo-3d" style="width: 400px; height: 400px;"></div>
<script>
const options = {
container: 'mini-tokyo-3d',
secrets: {
mapbox: '<Mapbox access token>'
}
};
const mt3d = new MiniTokyo3D(options);
</script>
</body>
To embed Mini Tokyo 3D into your application code using a bundler, follow the steps below.
First, install the npm module of Mini Tokyo 3D and register it to your application's package.json
.
npm install mini-tokyo-3d --save
If you want to load the module in the CommomJS style, you need to include the following at the beginning of your code.
const MiniTokyo3D = require('mini-tokyo-3d');
To load the module in the ES6 style, you need to include the following at the beginning of your code.
import MiniTokyo3D from 'mini-tokyo-3d';
In your application code, you need to initialize the MiniTokyo3D object as follows. container
of the options
object represents the ID of the HTML element in which Mini Tokyo 3D will render the map. You also need to specify the Mapbox access token obtained in the above step to secrets.mapbox
.
const options = {
container: '<container element ID>',
secrets: {
mapbox: '<Mapbox access token>'
}
};
const mt3d = new MiniTokyo3D(options);
Using Mini Tokyo 3D API in JavaScript, you can customize Mini Tokyo 3D in a variety of ways.
Note: The Mini Tokyo 3D API is currently in beta. Due to the possibility of API changes, compatibility between versions is not guaranteed.
The MiniTokyo3D
object represents the Mini Tokyo 3D map on your page. You create a MiniTokyo3D
by specifying a container
and other options
. Then Mini Tokyo 3D initializes the map on the page and returns your MiniTokyo3D
object.
new MiniTokyo3D(options: Object)
options
(Object
)
Name | Description |
---|---|
options.container string |
The id of the HTML element in which Mini Tokyo 3D will render the map. |
options.secrets Secrets |
An object to store the access tokens used to retrieve data. |
options.lang string |
IETF language tag for the language. If not specified, the browser's default language is used. Currently 'ja' , 'en' , 'ko' , 'zh-Hans' , 'zh-Hant' , 'th' and 'ne' are supported. If an unsupported language is specified, then 'en' is used. |
options.dataUrl string |
Mini Tokyo 3D data URL. If not specified, 'https://minitokyo3d.com/data' will be used. |
options.clockControl boolean default: true |
If true , the date and time display will be added to the map. |
options.searchControl boolean default: true |
If true , the search button will be added to the map. |
options.navigationControl boolean default: true |
If true , the navigation buttons will be added to the map. |
options.fullscreenControl boolean default: true |
If true , the fullscreen button will be added to the map. |
options.modeControl boolean default: true |
If true , the mode switch buttons will be added to the map. |
options.configControl boolean default: true |
If true , the configuration buttons will be added to the map. |
options.trackingMode string default: 'helicopter' |
The initial tracking mode. 'helicopter' and 'heading' are supported. |
options.ecoMode string default: 'normal' |
The initial eco mode. 'normal' and 'eco' are supported. |
options.center LngLatLike default: [139.7670, 35.6814] |
The initial geographical center point of the map. If not specified, it will default to around Tokyo station ([139.7670, 35.6814] ). Note: Mini Tokyo 3D uses longitude, latitude coordinate order to match GeoJSON. |
options.zoom number default: 14 |
The initial zoom level of the map. If not specified, it will default to 14 . |
options.bearing number default: 0 |
The initial bearing (rotation) of the map, measured in degrees counter-clockwise from north. If not specified, it will default to the true north (0 ). |
options.pitch number default: 60 |
The initial pitch (tilt) of the map, measured in degrees away from the plane of the screen (0-85). If not specified, it will default to 60 . |
options.ecoFrameRate number default: 1 |
Frame rate for train and airplane animations (frames per second) when Eco Mode is on. Specify on a scale of 1 to 60. Lower values result in less smoother animations and lower CPU resource usage, thus reducing battery consumption on mobile devices. If not specified, it will default to 1 . |
options.selection string |
ID of the train or flight to be tracked. The train ID is a string in the form of 'odpt.Train:<operator ID>.<railway ID>.<train number>' . The fright ID is a string in the form of 'odpt.FlightInformationArrival:<operator ID>.<airport ID>.<flight number>' or 'odpt.FlightInformationDeparture:<operator ID>.<airport ID>.<flight number>' . The 'odpt.*:' part can be omitted. For details, see the Open Data Challenge for Public Transportation in Tokyo: API Specification. |
Changes any combination of center, zoom, bearing, pitch, and padding with an animated transition between old and new values. The map will retain its current values for any details not specified in options
.
Note: The transition will happen instantly if the user has enabled the reduced motion accessibility feature enabled in their operating system, unless options
includes essential: true
.
options
(Object
) Options describing the destination and animation of the transition. Accepts CameraOptions
and AnimationOptions
.
MiniTokyo3D
: this
Changes any combination of center, zoom, bearing, and pitch, animating the transition along a curve that evokes flight. The animation seamlessly incorporates zooming and panning to help the user maintain her bearings even after traversing a great distance.
Note: The animation will be skipped, and this will behave equivalently to jumpTo
if the user has the reduced motion
accessibility feature enabled in their operating system, unless options
includes essential: true
.
options
(Object
) Options describing the destination and animation of the transition. Accepts CameraOptions
, AnimationOptions
, and the following additional options.
Name | Description |
---|---|
options.curve number default: 1.42 |
The zooming "curve" that will occur along the flight path. A high value maximizes zooming for an exaggerated animation, while a low value minimizes zooming for an effect closer to MiniTokyo3D#easeTo . 1.42 is the average value selected by participants in the user study discussed in van Wijk (2003). A value of Math.pow(6, 0.25) would be equivalent to the root mean squared average velocity. A value of 1 would produce a circular motion. |
options.minZoom number |
The zero-based zoom level at the peak of the flight path. If options.curve is specified, this option is ignored. |
options.speed number default: 1.2 |
The average speed of the animation defined in relation to options.curve . A speed of 1.2 means that the map appears to move along the flight path by 1.2 times options.curve screenfuls every second. A screenful is the map's visible span. It does not correspond to a fixed physical distance, but varies by zoom level. |
options.screenSpeed number |
The average speed of the animation measured in screenfuls per second, assuming a linear timing curve. If options.speed is specified, this option is ignored. |
options.maxDuration number |
The animation's maximum duration, measured in milliseconds. If duration exceeds maximum duration, it resets to 0. |
MiniTokyo3D
: this
Returns the map's current bearing. The bearing is the compass direction that is "up"; for example, a bearing of 90° orients the map so that east is up.
number
: The map's current bearing.
Returns the map's geographical centerpoint.
LngLat
: The map's geographical centerpoint.
Returns the current clock mode.
string
: A string representing the current clock mode. Either 'realtime'
or 'playback'
.
Returns the current eco mode.
string
: A string representing the current eco mode. Either 'normal'
or 'eco'
.
Returns the map's current pitch (tilt).
number
: The map's current pitch, measured in degrees away from the plane of the screen.
Returns the ID of the train or flight being tracked.
string
: The ID of the train or flight being tracked. The train ID is a string in the form of '<operator ID>.<line ID>.<train number>'
. The flight ID is a string in the form of '<operator ID>.<airport ID>.<flight number>'
.
Returns the current tracking mode.
string
: A string representing the current tracking mode. Either 'helicopter'
or 'heading'
.
Returns the current view mode.
string
: A string representing the current view mode. Either 'ground'
or 'underground'
.
Returns the map's current zoom level.
number
: The map's current zoom level.
Changes any combination of center, zoom, bearing, and pitch, without an animated transition. The map will retain its current values for any details not specified in options
.
options
(CameraOptions
) Options object
MiniTokyo3D
: this
Removes an event listener previously added with MiniTokyo3D#on
.
type
(string
) The event type previously used to install the listener.
listener
(Function
) The function previously installed as a listener.
MiniTokyo3D
: this
Adds a listener for events of a specified type.
type
(string
) The event type to listen for.
listener
(Function
) The function to be called when the event is fired.
MiniTokyo3D
: this
Adds a listener that will be called only once to a specified event type.
type
(string
) The event type to add a listener for.
listener
(Function
) The function to be called when the event is fired.
MiniTokyo3D
: this
Sets the map's bearing (rotation). The bearing is the compass direction that is "up"; for example, a bearing of 90° orients the map so that east is up.
Equivalent to jumpTo({bearing: bearing})
.
bearing
(number
) The desired bearing.
MiniTokyo3D
: this
Sets the map's geographical centerpoint. Equivalent to jumpTo({center: center})
.
center
(LngLatLike
) The centerpoint to set.
MiniTokyo3D
: this
Sets the clock mode. In the real-time clock mode ('realtime'
), trains and airplanes are displayed on the map according to the actual operation at the current time. In the playback clock mode ('playback'
), you can specify the time and the speed of time passing.
mode
(string
) A string representing the clock mode. Either 'realtime'
or 'playback'
.
MiniTokyo3D
: this
Sets the eco mode. In the normal mode ('normal'
), the frame rate for train and airplane animations will be set to 60. In the eco mode ('eco'
), the frame rate will be set to the MiniTokyo3D
constructor option ecoFrameRate
.
mode
(string
) A string representing the eco mode. Either 'normal'
or 'eco'
.
MiniTokyo3D
: this
Sets the map's pitch (tilt). Equivalent to jumpTo({pitch: pitch})
.
pitch
(number
) The pitch to set, measured in degrees away from the plane of the screen (0-85).
MiniTokyo3D
: this
Sets the ID of the train or flight you want to track. The train ID is a string in the form of 'odpt.Train:<operator ID>.<railway ID>.<train number>'
. The fright ID is a string in the form of 'odpt.FlightInformationArrival:<operator ID>.<airport ID>.<flight number>'
or 'odpt.FlightInformationDeparture:<operator ID>.<airport ID>.<flight number>'
. The 'odpt.*:'
part can be omitted. For details, see the Open Data Challenge for Public Transportation in Tokyo: API Specification.
id
(string
) ID of the train or flight to be tracked.
MiniTokyo3D
: this
Sets the tracking mode. In the helicopter tracking mode ('helicopter'
), it makes a 360 degree turn around the target train or airplane. In the heading tracking mode ('heading'
), it tracks the target train or airplane from above or diagonally behind in the direction of travel up.
mode
(string
) A string representing the tracking mode. Either 'helicopter'
or 'heading'
.
MiniTokyo3D
: this
Sets the view mode. In the ground view mode (ground'
), ground railways, stations, trains and airplanes will be displayed brightly, and underground railways, stations and trains will be translucent. In the underground view mode ('underground'
), the map will turn dark and ground railways, stations, trains and airplanes will be translucent, while underground railways, stations and trains will appear brighter.
mode
(string
) A string representing the view mode. Either 'ground'
or 'underground'
.
MiniTokyo3D
: this
Sets the map's zoom level. Equivalent to jumpTo({zoom: zoom})
.
zoom
(number
) The zoom level to set (0-20).
MiniTokyo3D
: this
Fired when the user cancels a "box zoom" interaction, or when the bounding box does not meet the minimum size threshold. See BoxZoomHandler
.
data
(MapBoxZoomEvent
)
Fired when a "box zoom" interaction ends. See BoxZoomHandler
.
data
(MapBoxZoomEvent
)
Fired when a "box zoom" interaction starts. See BoxZoomHandler
.
data
(MapBoxZoomEvent
)
Fired when a pointing device (usually a mouse) is pressed and released at the same point on the map.
data
(MapMouseEvent
)
Fired when the clock mode is changed.
data
({mode:
string
}
)
Fired when the right button of the mouse is clicked or the context menu key is pressed within the map.
data
(MapMouseEvent
)
Fired when a pointing device (usually a mouse) is pressed and released twice at the same point on the map in rapid succession.
data
(MapMouseEvent
)
Fired when a train or airplane tracking is canceled.
data
({deselection:
string
}
)
Fired repeatedly during a "drag to pan" interaction. See DragPanHandler
.
data
({originalEvent:
DragEvent
}
)
Fired when a "drag to pan" interaction ends. See DragPanHandler
.
data
({originalEvent:
DragEvent
}
)
Fired when a "drag to pan" interaction starts. See DragPanHandler
.
data
({originalEvent:
DragEvent
}
)
Fired when the eco mode is changed.
data
({mode:
string
}
)
Fired when an error occurs. This is Mini Tokyo 3D's primary error reporting mechanism. We use an event instead of throw
to better accommodate asynchronous operations. If no listeners are bound to the error
event, the error will be printed to the console.
data
({error: {message:
string
}}
)
Fired immediately after all necessary resources have been downloaded and the first visually complete rendering of the map has occurred.
Fired when a pointing device (usually a mouse) is pressed within the map.
data
(MapMouseEvent
)
Fired when a pointing device (usually a mouse) is moved while the cursor is inside the map. As you move the cursor across the map, the event will fire every time the cursor changes position within the map.
data
(MapMouseEvent
)
Fired when a pointing device (usually a mouse) is moved within the map. As you move the cursor across a web page containing a map, the event will fire each time it enters the map or any child elements.
data
(MapMouseEvent
)
Fired when a pointing device (usually a mouse) is released within the map.
data
(MapMouseEvent
)
Fired repeatedly during an animated transition from one view to another, as the result of either user interaction or methods such as MiniTokyo3D#flyTo
.
data
((MapMouseEvent
| MapTouchEvent
))
Fired just after the map completes a transition from one view to another, as the result of either user interaction or methods such as MiniTokyo3D#jumpTo
.
data
({originalEvent:
DragEvent
}
)
Fired just before the map begins a transition from one view to another, as the result of either user interaction or methods such as MiniTokyo3D#jumpTo
.
data
({originalEvent:
DragEvent
}
)
Fired repeatedly during the map's pitch (tilt) animation between one state and another as the result of either user interaction or methods such as MiniTokyo3D#flyTo
.
data
(MapEventData
)
Fired immediately after the map's pitch (tilt) finishes changing as the result of either user interaction or methods such as MiniTokyo3D#flyTo
.
data
(MapEventData
)
Fired whenever the map's pitch (tilt) begins a change as the result of either user interaction or methods such as MiniTokyo3D#flyTo
.
data
(MapEventData
)
Fired immediately after the map has been resized.
Fired repeatedly during a "drag to rotate" interaction. See DragRotateHandler
.
data
((MapMouseEvent
| MapTouchEvent
))
Fired when a "drag to rotate" interaction ends. See DragRotateHandler
.
data
((MapMouseEvent
| MapTouchEvent
))
Fired when a "drag to rotate" interaction starts. See DragRotateHandler
.
data
((MapMouseEvent
| MapTouchEvent
))
Fired when a train or airplane tracking is initiated.
data
({selection:
string
}
)
Fired when a touchcancel
event occurs within the map.
data
(MapTouchEvent
)
Fired when a touchend
event occurs within the map.
data
(MapTouchEvent
)
Fired when a touchmove
event occurs within the map.
data
(MapTouchEvent
)
Fired when a touchstart
event occurs within the map.
data
(MapTouchEvent
)
Fired when the tracking mode is changed.
data
({mode:
string
}
)
Fired when the view mode is changed.
data
({mode:
string
}
)
Fired when a wheel
event occurs within the map.
data
(MapWheelEvent
)
Fired repeatedly during an animated transition from one zoom level to another, as the result of either user interaction or methods such as MiniTokyo3D#flyTo
.
data
((MapMouseEvent
| MapTouchEvent
))
Fired just after the map completes a transition from one zoom level to another, as the result of either user interaction or methods such as MiniTokyo3D#flyTo
.
data
((MapMouseEvent
| MapTouchEvent
))
Fired just before the map begins a transition from one zoom level to another, as the result of either user interaction or methods such as MiniTokyo3D#flyTo
.
data
((MapMouseEvent
| MapTouchEvent
))
The Secrets
object is an object that stores the access tokens used to retrieve data and is set to the MiniTokyo3D
constructor option secrets
.
tokyochallenge
(string
) : Access token for the Open Data Challenge for Public Transportation in Tokyo. If not specified, the default token will be used.
odpt
(string
) : Access token for the Public Transportation Open Data Center. If not specified, the default token will be used.
mapbox
(string
) : Access token for Mapbox. If you don't specify this token, an error will occur when loading the map, so make sure to get an access token specific to your web site.
If you want to try out the latest features before they are released, modify the code yourself, or contribute to Mini Tokyo 3D development, you can build your project from source code by following the instructions in this section.
The following software are required.
Mini Tokyo 3D uses the following data sources and requires an access token for each of them at build time. Follow the instructions below to obtain access tokens.
Data Source | Sign-Up URL | Access Token Format |
---|---|---|
Open Data Challenge for Public Transportation in Tokyo | Link | A string of numbers and lowercase letters |
Public Transportation Open Data Center | Link | A string of numbers and lowercase letters |
Mapbox | Link | Alphanumeric string containing a period beginning with pk. |
Mini Tokyo 3D is using train and airplane data from the Open Data Challenge for Public Transportation in Tokyo. You need to register as a developer to get the data, but it is available for free.
- Register as a developer by entering your user information on the developer site's registration page. It may take a few days to receive your registration confirmation email.
- After logging in with your developer account, click on "Account" in the menu at the top of the screen and select "Manage Access Token".
- A list of access tokens will be displayed. Only the "DefaultApplication" token will be displayed right after creating the account. Click on "Issuing an access token".
- Enter an application name in the "Name" field and click the "Submit" button.
- The newly created token will appear in the list of access tokens
Mini Tokyo 3D is also using data from the Public Transportation Open Data Center. Again, you need to register as a developer to get the data, but it is available for free.
- Register as a developer by entering your user information on the developer site's registration page. It may take a few days to receive your registration confirmation email.
- After logging in with your developer account, click on "Account" in the menu at the top of the screen and select "Manage Access Token".
- A list of access tokens will be displayed. Only the "DefaultApplication" token will be displayed right after creating the account. Click on "Issuing an access token".
- Enter an application name in the "Name" field and click the "Submit" button.
- The newly created token will appear in the list of access tokens
See Getting a Mapbox Access Token.
Download the latest master
branch from Mini Tokyo 3D's GitHub repository and extract the zip file. A directory named mini-tokyo-3d-master
will be created, so change the name to mini-tokyo-3d
.
curl -LO https://github.com/nagix/mini-tokyo-3d/archive/master.zip
unzip master.zip
mv mini-tokyo-3d-master mini-tokyo-3d
If you are using Git, you can clone the repository directly from GitHub instead of the above commands.
git clone https://github.com/nagix/mini-tokyo-3d.git
Go to the top directory of Mini Tokyo 3D.
cd mini-tokyo-3d
Create a JSON file containing the access tokens obtained in the build preparation step and save it in this directory with the file name secrets
.
{
"tokyochallenge": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"odpt": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"mapbox": "pk.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxx"
}
Install the dependent npm modules.
npm install
Build the project with the following command.
npm run build-all
When the build completes successfully, the dist
directory will be created. It includes style sheet and JavaScript files for distribution. The build
directory will also be created at the same time. It contains all the files needed for deployment on your web site.
The index.html
in the build
directory is for the web page on https://minitokyo3d.com. Edit it for your web site, and place all the files in the build
directory in the public directory of your web server.