Change history
| Date |
Change |
| 15/12/2009 |
|
| 15/12/2009 |
- Change to 'size' param specification for 2D objects, which will be implemented in the next version of the clients
- Change to the maximum file size for 2D images (75 kB)
|
Introduction
When creating your layer, you now have the option to indicate that your layer is using the new 3d features. Your layer can contain actual 3d objects or it can use 2d objects (images) placed accurately in 3d space. In both cases, you should change your layer type using the pull-down menu provided:
- generic: The layers used in v1 and v2 clients
- 3d: 3d and 2d objects are placed in 3d space
POI objects with 3D/2D
These additional parameters can be sent in the POI (hotspot) dictionary. All parameters are optional.
Key
|
Value
|
Example
|
Explanation
|
|
dimension
|
integer
|
"dimension":2
|
1: 1d - usual POI (icons). Default value (if no value is supplied, the usual 1d POI is assumed)
2: 2d - image used for POI
3: 3d - 3d object used for POI
|
|
alt
|
integer
|
"alt":2550
|
Optional.
Real altitude of object in meters. If this is missing, the same altitude as the user is assumed
|
|
transform
|
json dictionary
|
see below
|
Mandatory if dimension is 2 or 3.
Determines how to place the object in space.
|
|
object
|
json dictionary
|
see below
|
Mandatory if dimension is 2 or 3.
Determines the location of the representations of the object (files to download)
|
|
relativeAlt
|
integer
|
"relativeAlt":2
|
Optional.
Altitude in meters of the object with respect to the user's altitude.
|
Transform dictionary
All values are mandatory.
Key
|
Value
|
Example
|
Explanation
|
|
rel
|
boolean
|
"rel":true
|
If this value is true, the rotation is calculated relative to the position of the user: the object will always face the user in the same way regardless of the absolute direction. In most cases angle will be 0 when rel is true.
So with rel=true, the user isn't able to walk around the object in order to view the back of it.
|
|
angle
|
decimal
|
"angle":-90
|
When designing an object, the x axis is aligned in the W-E direction, while the y axis is aligned in the S-N direction.
This parameter is the rotation angle in degrees to rotate the object around its z-axis. The rotation direction is determined by the usual right-hand thumb rule (positive angle: counter clock-wise in the x-y plane). So for the example of -90, this means the object is oriented toward the East: a user looking toward the East will see the object as it was designed.
|
|
scale
|
decimal
|
"scale":3.0
|
The size of 3d objects is determined by the object themselves (unit of the coordinate system is 1m). For 2d objects, 200 pixels is 1m. This scale factor is to be used to scale the object to different sizes.
|
Note for 2d objects: The coordinate system for 2d objects is such that the picture lies in the xz-plane (x-axis horizontal), with the y axis pointing outward at the back of the 2d object.
Scaling of 2d-objects:
Note: This will be changed in the next version of the client, we'll use the 'size' parameter instead.
200 pixels/meter (e.g. a 320x180 picture would be displayed as a 1.6x0.9m poster). 2d pics must always have a resolution less than 320x480 pixels as a guideline. In order to get larger real-life sizes for the same resolution, the 'scale' param can be used.
Object dictionary
|
Key
|
Value
|
Example
|
Explanation
|
|
baseURL
|
URL
|
"baseURL":"http://layer.coolservice.com/3dobjects/globe/"
|
The URL to base the paths to the various objects on
|
|
full (mandatory if dimension is 2 or 3)
|
string
|
"full": "near.l3d" or "full": "?object=myobject
&configuration=near" or "full": "near.png"
|
The object representation when it is closes to the user (full view of the object, up to about 50 m). The relative path to the file or relative URL to call in order to fetch the object.
|
|
reduced
(optional)
|
string
|
"reduced": "reduced.l3d" or "reduced": "?object=myobject
&config=reduced"
|
The object representation when it is not so close anymore that full detail is required (ca. 50-100m). This should be a small scale 3d object.
|
|
icon
(optional)
|
string
|
"icon": "far.png"
|
The 2d object representation when it is far away. This is just an icon and won't use the direction vector. Use a 32x32 PNG file here.
This can also be set for dimension=1, in order to have custom icons per POI (instead of using the type parameter).
|
| size (mandatory if dimension is 2 or 3) |
float |
"size":32.5 |
The size of the object in m. This is the length of the edge of the smallest cube in which the object can fit. Note that this is the size before any transform ('scale') is applied to the object.
For 3D objects: The size is used by the client to determine when it can switch from 'icon' to 'reduced' to 'full' (actually size * scale will be used). So it's not required to be very precise.
For 2D objects (next version of the client): The size will be used to actually scale the 2D image, independent of its resolution. So make sure the size you use is correct! It's the height of your 2D image in z-direction.
|
Fallbacks (client side):
If any of the files cannot be downloaded, the client will use a fallback mechanism using the icons defined globally for the layer:
-
If the 'full' 3d object is missing, the client should use a special icon indicating a missing file. It should be clear to the user that a 3d object is supposed to be here. The client should try to download again if failure is due to a time-out.
-
In other cases, use the next level object file if it is available (e.g. 'reduced' image if the 'full' image is missing
-
Next, use the custom CIWs of the layer if those are defined (and correspond to the 'type' attribute of the POI)
-
Finally use the default layer icons.
Object specifications
3D objects
- 'full': Use at most 5000 polygons (triangles).
- 'reduced': Use at most 500 polygons
- Textures: For the textures to work in the Layar client, the image width and height should be in powers of 2 up to 512, so 256x256, 128x128 are valid, but 512x512, or even 512x256 would also be allowed. They can be .png or .jpg. Try not to use larger tiles, remember the screen resolution is 320x480 so larger tiles make little sense.
- Transparency in textures: Is supported if you use PNG. Note we need to solve an issue when objects are behind each other.
- How to add the textures: For texturing in general, you should use your 3D modeling software of choice and create your model, including the texturing. When you export the model to the Wavefront format, two files will be created: .obj and .mtl. The .mtl file refers to the materials used in the model and each material can refer to texture images. UV coordinates will be in the .obj file. When converting the .obj/.mtl to .l3d, all texture images will be embedded in the .l3d object, so you will have a single model file that you can use in you Layer service.
- When exporting to .obj/.mtl, use grouping by material if your software supports this. This allows that the object is drawn with fewer openGL calls which can greatly improve the performance when you use your materials on several parts of your model.
2D Objects
- Currently the size of the 2D object is determined by its resolution. This is problematic, because full and reduced need to be the same resolution if the object has a specific real-life size. We'll change that in the next client version to be determined by the 'size' param, so make sure you specify the 'size' param correctly!
- 'full': Maximum resolution is 640x480. Remember the screen is in most cases 320x480 so high resolution doesn't make sense.
- 'reduced': Maximum resolution is 240x180.
- All images must be smaller than 75kB
- Transparency: Is supported. Note we still need to solve an issue when objects are behind each other.
Comments (2)
Thomas Emge said
at 3:49 am on Jan 15, 2010
I would like to get some clarification on how to embed the textures: I currently have an .obj, a .mtl, and a jpg file (256x256) as the texture. When I use the model converter tool I do end up with a very tiny .l3d. In my opinion the .l3d file is too small to contain the texture jpg file as described above and when I do attempt to serve out the generated .l3d file, the Layar client simply crashes. How can I troubleshoot the situation if it is the model (my obj/mtl/jpg combination) or the l3d itself file that is causing the issue?
Thomas Emge said
at 4:02 am on Jan 15, 2010
Ok, one more addition...as opposed to running the converter through the UI window I did run it in the command line and I got the following error message:
Exception in thread "main" java.lang.NullPointerException
at com.layar.model3d.Layar3DModelLoader.save(Layar3DModelLoader.java:56)
at com.layar.model3d.ModelConverter.main(ModelConverter.java:400)
Any suggestions are highly appreciated.
You don't have permission to comment on this page.