# How to Batch Create Materials to PDC

When you need to upload lots of materials, a good practice is to create the data in a correct way to be able to import it in a batch using the PDC's import feature. You can do it in the Roomle Product Data Cloud (opens new window) catalogue's Import/Export page. If you do not have the top navigation bar or it does not have the Import/Export page link, you probably do not have the needed rights.

This is a step-by-step guide that will guide you through the process.

  1. In the Git catalogue's materials folder, create a materials_import.csv file (file name is not relevant, use another if not available). We recommend having all textures in one folder, with following structure:
  • materialname_thumbnail.png
  • materialname_rgb.png
  • materialname_orm.png
  • materialname_xyz.png

Where material name is chosen so that you know which texturs belong to which material. The filenames are not relevant at all, but we still recommend keeping resonable suffixes. RGB could be albedo/diffuse, XYZ is also called a normal map.

Note: Thumbnail will be created from the _rgb texture by rescaling it down to 256x256mm. However, it might happen that you need a small cutout of the texture, so that you can see the pattern. In this case, you must supply your own thumbnail. We recommend using a batch image processing tool, that will allow you to export a defined cutout from the images to achieve this.

If you reuse one texture in more materials, which is a case for example for one fabric type in different colours, where the _rgb and _thumbnail are different, but the other maps are the same, it is good ot name it in a way you can distinguish what belongs to what.

  1. Place the texture files in the relevant subfolders.

  2. Open the CSV file and create a header

"material_id","label_en","shading","thumbnail","tex0_mapping","tex0_mmHeight","tex0_mmWidth","tex0_tileable","tex0_image"

Let's stop here for a minute. In the header, you must declare all columns you are going to upload. This header is for the situation, where you upload a material with an english label, an RGB map and a thumbnail. If oyu want to upload labels in more languages, simply add relevant columns, like label_de, label_ru etc. If you have more maps, you will have to make 5 more columns for every map type, which will be called tex1, text2, etc. instead of tex0. Therefore, if we are also going to upload normal maps, we write:

"material_id","label_en","shading","thumbnail","tex0_mapping","tex0_mmHeight","tex0_mmWidth","tex0_tileable","tex0_image","tex1_mapping","tex1_mmHeight","tex1_mmWidth","tex1_tileable","tex1_image"

Important warning: The CSV you are batch uploading the textures with using the columns with prefixes tex0 to texN is a snapshot of the final state after upload. That means if you have already uploaded RGB textures using one CSV, uploading another CSV with only XYZ will NOT result in adding normals, but (untinentionally) DELETING CURRENT TEXTURES and replacing them with only hte XYZ maps. In order to achieve this, you need to upload both RGB and XYZ in a single CSV.

  1. Fill in the values:
  • material_id: the unique identifier of the material. This can not be changed after the import.
  • label_en: label that shows in the end-user interface
  • shading: serialized Json that holds the shading data ... see how to fill shading below
  • thumbnail: relative path to the thumbnail image file. Example: zip://thumbnails/leather_red.png
  • tex0_mapping: mapping of the texture with number 0. Can be: RGB, RGBA, XYZ, ORM
    • RGB - Standard, non-transparent mapping
    • RGBA - As above + has a transparency alpha channel. This is rare and relevant for transparent textures. Hint: JPGs don't have a alpha channel, PNGs do.
    • XYZ - Normal map
    • ORM - Ambient Occlusion - Roughness - Metallness map.
  • tex0_mmHeight and tex0_mmWidth: size of the cutout of the texture in reality
  • tex0_tileable: true/false or 1/0, sets the tileability flag of the texture
  • tex0_image: relative address of the texture file. Example: zip://textures/leather_red.png
  • tex1_ ...: fill in relevant values for the other textures as well

If you use more maps, keep a convention that you use tex0 for RGB or RGBA, tex1 for normal maps, tex2 for ORM maps.

Shading explanation

Shading is a Json that provides values for the shader. Full class source code:

{
    "basecolor": {
        "r": 1,
        "g": 1,
        "b": 1
    },
    "alpha": 1,
    "metallic": 0,
    "roughness": 0.9,
    "doubleSided: false
}
  • r, g, b: Values are normalized (values between <0..1>). To get them from <0..255>, simply divide by 255. To get color form hex, you must use a converter.
  • alpha: Opacity of the material between <0..1> from fully transparent (invisble) to fully opaque. If alpha < 1, material is treaded as transparent, being more expensive to render.
  • metallic: Metallness value of the material. 0 or 1 - dielectric or metal. Values in between correlate, but most values near to, or exactly 0 or 1 are suitable. Watch out that painted metal is not metallic = 1 (the paint on it is usually dielectric).
  • rougness: <0..1> from glossy to fully matt. Warning: Exactly 0 is overriden by a value of around 0.7. For most glossy surface, use near 0 values like 0.01.
  • doubleSided: The material applies to both sides of the mesh, irrelevant of the normal direction. This is expensive to render and should be avoided if not needed.

If you use ORM maps, relevant alpha, roughness and metallic are coefficient to the value from maps. Use 1 in all those values in order to follow the exact values of the ORM maps.

RGB values are overriden by the RBG/RGBA maps, meaning you can not use those values to make color variations of a texture.

To use the shading Json inside a CSV, you must stringify it and escape quotes:

"material_id","shading"
"material_test","{""basecolor"":{""r"":1,""g"":1,""b"":1},""alpha"":1,""metallic"":0,""roughness"":0.9,""doubleSided:false}"
  1. The resulting file should look like this:
"material_id","label_en","shading","thumbnail","tex0_mapping","tex0_mmHeight","tex0_mmWidth","tex0_tileable","tex0_image","tex1_mapping","tex1_mmHeight","tex1_mmWidth","tex1_tileable","tex1_image"
"lux_red","Leather Lux Red","{""basecolor"":{""r"":1,""g"":1,""b"":1},""alpha"":1,""metallic"":0,""roughness"":0.9,""doubleSided:false}","zip://thumbnails/leather_red_thumb.png","RGB","200","300","1","zip://textures/leather_lux_red.png","XYZ","200","300","1","zip://normalmaps/leather_normal.png"
  1. Once you are ready with the import, zip all the folders and the CSV file and drop it into the import field of materials.

If the file is too big, it is probable that the PDC will hit a timeout. In this case, try to upload fewer entries at once.

  1. Make a commit with the prepared data.

  2. Delete all but a number (try around 10) of the entries including the textures to make the upload smaller.

  3. After a successful import, discard the changes in Git and continue with the next entries.