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