1Models
2======
3
4A common asset stored in an Ignition Fuel server is a model. A model represents
5an object in simulation. A model has a name and a description of its visual and
6physical properties. Models can be as simple as a sphere or complicated as a
7highly articulated humanoid robot.
8
9Ignition Fuel Tools lets you perform a set of operations over the models
10hosted in any Ignition Fuel server. These operations allow you to list all
11models of a particular server, get the details of a model or download a model.
12
13We're going to run a few examples, so let's start by creating a directory for
14this tutorial:
15
16```
17mkdir /tmp/models_tutorial && cd /tmp/models_tutorial
18```
19
20Download the files `modelList.cc`, `modelDetails.cc`, `ModelDownload.cc`,
21`CMakeLists.txt`, and save them under `/tmp/models_tutorial`:
22
23```
24wget https://bitbucket.org/ignitionrobotics/ign-fuel-tools/raw/ign-fuel-tools1/example/modelList.cc
25wget https://bitbucket.org/ignitionrobotics/ign-fuel-tools/raw/ign-fuel-tools1/example/modelDetails.cc
26wget https://bitbucket.org/ignitionrobotics/ign-fuel-tools/raw/ign-fuel-tools1/example/modelDownload.cc
27wget https://bitbucket.org/ignitionrobotics/ign-fuel-tools/raw/ign-fuel-tools1/example/CMakeLists.txt
28```
29
30Let's start by compiling the examples:
31
32```
33mkdir build && cd build
34cmake ..
35make
36```
37
38## List models from a Fuel server
39
40Run the following example to see the list of models hosted in the default
41server:
42
43```
44./modelList
45```
46
47You should see the name of the server followed by its list of models. Here's an
48example:
49
50```
51[https://api.ignitionfuel.org]
52
53  Beer
54  Wastebasket
55  ambulance3
56  ambulance2
57  appartment3
58  hammer
59  another test model
60  Test Model
61  Bowl
62  Cardboard Box
63  Cessna C-172
64  Fire station (collapsed)
65  Beer
66  Apartment
67  Ambulance
68```
69
70### Walkthrough
71
72This example contains some boilerplate to parse command line arguments and load
73some configuration. Refer to the [configuration tutorial](https://ignitionrobotics.org/tutorials/fuel_tools/1.0/md__data_ignition_ign-fuel-tools_tutorials_configuration.html)
74for details about this part of the code. Let's focus on the relevant code for
75listing models:
76
77```
78for (const auto &server : client.Config().Servers())
79{
80  std::cout << "[" << server.URL() << "]\n\n";
81  for (auto iter = client.Models(server); iter; ++iter)
82    std::cout << "  " << iter->Identification().Name() << "\n";
83  std::cout << std::endl;
84}
85```
86
87As you can see, we're iterating over the list of servers. For each server, we
88use the `Models()` method to retrieve all models of that server. Then, we go
89over each model using an iterator and call the `Identification()` method from
90the `Model` class. `Identification()` returns an object of type
91`ModelIdentifier()` containing most of the properties of the model. In our
92case, we just show the name.
93
94## Get details of a model
95
96Run the following example to see the details of a model hosted in the default
97server:
98
99```
100./modelDetails -o caguero -m Beer
101```
102
103You should see the name of the server followed by the details of the model.
104Here's an example:
105
106```
107[https://api.ignitionfuel.org]
108
109  Name: Beer
110  Source URL: https://api.ignitionfuel.org
111  Unique name: https://api.ignitionfuel.org/1.0/caguero/models/Beer
112  Owner: caguero
113  Description: A beer can
114  Likes: 0
115  Downloads: 3
116  License name: Creative Commons - Attribution
117  License URL: http://creativecommons.org/licenses/by/4.0/
118  License image URL: https://i.creativecommons.org/l/by/4.0/88x31.png
119  Tags:
120```
121
122### Walkthrough
123
124This example contains some boilerplate to parse command line arguments and load
125some configuration. Refer to the [configuration tutorial](https://ignitionrobotics.org/tutorials/fuel_tools/1.0/md__data_ignition_ign-fuel-tools_tutorials_configuration.html)
126for details about this part of the code. Let's focus on the relevant code for
127getting details of a model:
128
129```
130// Fetch the model details.
131for (const auto &server : client.Config().Servers())
132{
133  ignition::fuel_tools::ModelIdentifier model;
134  if (!client.ModelDetails(server, modelIdentifier, model))
135    continue;
136
137  // Show server.
138  std::cout << "[" << server.URL() << "]\n\n";
139
140  // Show model details.
141  std::cout << "  Name: " << model.Name() << std::endl;
142  std::cout << "  Source URL: " << model.Server().URL() << std::endl;
143  std::cout << "  Unique name: " << model.UniqueName() << std::endl;
144  std::cout << "  Owner: " << model.Owner() << std::endl;
145  std::cout << "  Description: " << model.Description() << std::endl;
146  std::cout << "  Likes: " << model.Likes() << std::endl;
147  std::cout << "  Downloads: " << model.Downloads() << std::endl;
148  std::cout << "  License name: " << model.LicenseName() << std::endl;
149  std::cout << "  License URL: " << model.LicenseURL() << std::endl;
150  std::cout << "  License image URL: " << model.LicenseImageURL() << std::endl;
151  std::cout << "  Tags: " << std::endl;
152  for (auto const &tag : model.Tags())
153    std::cout << "  " << tag << std::endl;
154}
155```
156
157As usual, we're iterating over the list of servers. For each server, we
158use the `ModelDetails()` method to retrieve most of the properties of the model.
159Note that the result of `ModelDetails` is set in `model`, which is an
160object of type `ModelIdentifier`. If the model is found in the server, we use
161`model` to show most of its relevant fields.
162
163## Download a model
164
165Run the following example to download a model from the default server:
166
167```
168./modelDownload -o caguero -m Beer
169```
170
171Verify that you have the model in `$HOME/.ignition/fuel/models/`.
172
173### Walkthrough
174
175This example contains some boilerplate to parse command line arguments and load
176some configuration. Refer to the [configuration tutorial](https://ignitionrobotics.org/tutorials/fuel_tools/1.0/md__data_ignition_ign-fuel-tools_tutorials_configuration.html)
177for details about this part of the code. Let's focus on the relevant code for
178download a model:
179
180```
181// Fetch the model.
182for (const auto &server : client.Config().Servers())
183{
184  if (client.DownloadModel(server, modelIdentifier))
185    return 0;
186}
187```
188
189The previous block code iterates over all available Fuel servers and tries to
190download the requested model using the `DownloadModel()` method.
191