config-sample.yml

# The name of the app; this will be the unique identifier and path of the app, e.g. localhost:2222/apps/amnh/
name: amnh

# Site metadta to be used in the meta tags and introduction screen
title: "Collectionscope Demo: American Museum of Natural History"
titleFormatted: "Collection<strong>scope</strong> Demo" # May contain HTML
description: Explore the Museum’s collections across time and space.
introductionText: There are <strong>9,369 anthropology objects</strong> on display at the <a href="https://amnh.org" target="_blank">American Museum of Natural History</a>, but this is only <strong>2 percent</strong> of the Museum’s collections! Where were these objects collected? When were they collected? And why were they chosen? Let’s explore.
 # May contain HTML
creditText: The <a href="https://amnh-sciviz.github.io/collectionscope/" target="_blank">CollectionScope Tool</a> is a part of the Knight Foundation's <a href="https://knightfoundation.org/press/releases/shaping-the-future-of-technology-in-museums-knight-invests-750000-in-five-experiments-using-immersive-technology-in-the-arts/" target="_blank">Immersive Technology in the Arts Fund</a> # May contain HTML
credits:
  - name: American Museum of Natural History
    url: https://amnh.org/
    image: ../../img/amnh_logo.png # this path is relative to your /apps/{your project}/index.html file

  - name: Knight Foundation
    url: https://knightfoundation.org/
    image: ../../img/knight_logo.png

#################################
# Define your meta data source
#################################
# this can be an absolute path or a path relative to the `make_app.py` script
  # you can download this sample data here: https://www.dropbox.com/s/2isyfrkqp8y7860/AMNH_Anthro_Objects_2021-03-24.csv?dl=1
  # and place it in the ./data/ folder
metadataFile: data/AMNH_Anthro_Objects_2021-03-24.csv
# Basic query for filtering out metadata if applicable; comment this out or leave blank if you want all the data
  # Supports the following: =, !=, <, >, <=, >=, CONTAINS, EXCLUDES, EXISTS, AND, OR
  # Examples:
    # Year >= 1900 AND Year <= 2000
    # Description CONTAINS Portrait OR Description CONTAINS Figure
    # Image EXISTS True AND Image != no image
  # String conditions are case-insensitve
  # Parentheses currently not supported
metadataFilterQuery: Acquisition Year < 9999 AND Latitude < 9999 AND Longitude < 9999 AND Region != Europe
# column that contains a unique identifier for each item
identifierColumn: Catalog No

#################################
# Dates
#################################
# If you data has a date column, enter it here, otherwise comment it out
  # Note that this can be a date string in any format as long as the year is 4-digits within the valid year range
  # For example '1979', '1979-01-01', 'January 1, 1979' are all valid, while '1/1/79' is not valid since the year is ambiguous.
  # Regular expressions will be used to extract the year automatically, so the format doesn't need to be consistent
dateColumn: Acquisition Year
dateLabel: Acquisition Year # name of this date for displaying to the user
# If there is a valid range of years for date, enter it here, otherwise comment it out.
  # Entries with invalid dates will be removed
minimumYear: 1600
maximumYear: 2050

#################################
# Location
#################################
# Latitude and longitude values as floats are required for location-based visualization
  # E.g. NYC would have latitude 40.674239442221605 and longitude -74.02503271185628
  # If you do not have lat/lon values but have countries, states, cities, and/or addresses,
    # there is a script for geocoding these: see `scripts/geocode_locations.py`
    # if you used this process, "Latitude" and "Longitude" columns should have automatically been added
  # Entries with invalid or missing Lat/Lon will be excluded
latitudeColumn: Latitude
longitudeColumn: Longitude
# Country column is used for labelling countries in the map view; comment out or ignore if not applicable
countryColumn: Country
# This is the map that will be used for the map view
  # Replace with "../../img/world_map.png" for a map without region colors
baseMap: ../../img/world_map_with_regions.png # path is relative to your /apps/{your project}/index.html file
# And the map used for the map key in the map view
  # Replace with "img/world_map_key.png" for a map without region colors
baseMapKey: ../../img/world_map_key_with_regions.png # path is relative  to your /apps/{your project}/index.html file

#################################
# Group by
#################################
# This column will be used to group the items in different ways; ideally this would be somewhere between 3 and 12 unique groups
  # E.g. "Object type", "Subject", "Era", etc
  # If there are a large number of resulting groups, excess groups can be combined into an "Other" group which is configurable below
groupByColumn: Region
groupLabel: Region # the name of this column for displaying to the user
groupLimit: 8 # the maximum number of groups; if greater than this number, the last group will be "Other" (combination of all remainder groups); you can disable this in the next parameter
showOtherGroup: true # if number of groups exceeds the group limit above, combine the remaining groups into an "Other" group; if false, disregard remaining groups
otherLabel: Other # what to call the "Other" group if applicable
# Each group will be assigned a color for use in the UI
groupColors:
  - "#7aa030"
  - "#726aa4"
  - "#d37200"
  - "#d6a900"
  - "#529c99"
  - "#b13734"
  - "#1f3c90"
  - "#5a0661"

#################################
# Item details
#################################
# These are arbitrary fields that will be displayed to the user when they select an item
  # Comment any of these out if they are not applicable
  # Entries with blank or null values will not be displayed
itemFields:
  - column: Title
    isTitle: true # titles will be displayed as headings

  - column: URL
    label: View item details # labels support string formatting, e.g. View {Title}
    isLink: true # links will look like a button and hyperlink to a new window/tab

  - column: ImageURL
    isImage: true # images will be embedded in the page, so larger images will negaively impact the user experience since it will take longer to load

  - column: Catalog No
    label: Catalog Number

  - column: Acquisition Year
    label: Year acquired

  - column: Acquisition Type
    label: Type of acquisition

  - column: Country
    label: Country of origin

  - column: Donor
    label: Donor

#################################
# Images
#################################
# It is assumed you have all of the item images somewhere accessible from the computer you are
  # running the scripts from. If the images are somewhere else and accessible by URL, you
  # can run the following script for downloading these somewhere locally: `scripts/download_images.py`

# If you have a column in your .csv file that has the name of the image file, put it here.
  # Note if you ran `scripts/download_images.py`, this filename has been added to your .csv file
  # Alternatively you can define a format string, e.g. "{OtherColumnName}.jpg" (where "OtherColumnName"
    # is the name of an existing column in the .csv file)
filenameColumn: Filename

# Path to where the images are stored; again, you can use a format string based on existing column names
  # this can be an absolute path or a path relative to the `make_app.py` script
imageDirectory: E:/production/amnh/knight/images/{Region}/

# do images have a transparency value? (i.e. PNG images)
imageHasAlpha: false

# if image filename contains this value, treat it as if there's no image
noImageValue: no_image.jpg

# color of item if no image is present
defaultColor: "#3C3C3C"

#################################
# Visualizations
#################################
# This app currently supports a number of different visualizations. All of them are enabled by default
  # and you can customize or comment out any one that is not applicable to you.
  # Don't edit these if you want to see the default visualizations (recommended)

visualizations:
  # This places items randomly within a sphere
  randomSphere:
    radius: 8192 # increase this number to make less dense

  # This stacks item on top of a map; this will be disabled if no "latitudeColumn/longitudeColumn" fields are set above
  geographyBars:
    mapWidth: 8192 # increase this to make the map larger
    barHeight: 2048 # increase this to make the bars taller

  # This places the items along a "tunnel" organized by time; this will be disabled if no "dateColumn" field is set above
  timelineTunnel:
    radius: 256 # increase this to make the tunnel wider
    depthPerYear: 400 # increase this to make the tunnel longer

  # Places items along "tracks" based on "groupBy" categories along a timeline
  timelineTracks:
    trackWidth: 180 # width per each track; increase to make the tracks wider
    depthPerYear: 400 # increase this to make the tracks longer
    trackHeight: 512 # increase this to make the tunnel wider

#################################
# Stories
#################################
# This app gives you the opportunity to highlight and give context to specific parts of your collection
  # and overlay additional content and media. You can simply comment out this entire section if you want to
  # just visualize the data without any overlays
# All media paths should be relative to your /apps/{your project}/index.html file
# Currently all stories are "anchored" around a specific item; so you must pass in an item id for each (via column "identifierColumn" above)
  # if no item is passed in, a random item from the group will be assigned

stories:
  laufer:
    query: "Donor CONTAINS Laufer AND Country CONTAINS China AND Acquisition Year < 1910"
    itemId: "70 /10005"
    title: 1901-1904 Expedition to China
    slides:
      - html: >
          <p>This expedition led by Berthold Laufer collected everyday objects to understand the life of contemporary Chinese people.</p>
      - html: >
          <dt>How many objects were collected?</dt>
          <dd>7,500</dd>
      - html: >
          <dt>How many objects are currently exhibited?</dt>
          <dd>196</dd>
      - image: img/content/laufer/laufer_field_notes_0233.jpg
        imageAltText: A piece of paper with hand-written inventory of items collected
        html: >
          <p>Laufer's <a href="https://anthro.amnh.org/anthropology/databases/common/field_page.cfm?catno=70%20%20%2F10005" target="_blank">field notes</a> are one record of what was collected.</p>
      - image: img/content/laufer/laufer_field_notes_0233_moon_guitar.jpg
        imageAltText: A piece of paper with hand-written inventory of items collected with a row highlighted and an image of a wooden guitar under it
        html: >
          <p>One of these items is a wooden instrument called a <a href="https://anthro.amnh.org/anthropology/databases/common/public_access.cfm?object_list=70%20%20%2F10005" target="_blank">Moon Guitar</a></p>
      - itemId: "70 /10005"
        audio: audio/content/laufer/moon_lute.mp3
        html: >
          <p>Click on the icon above to hear a recording of a Moon Guitar</p>
          <p>Audio credit: <a href="https://www.amnh.org/explore/ology/anthropology/sounds-of-the-silk-road2/play-music" target="_blank">AMNH Ology</a></p>
      - image: img/content/laufer/silk_road_exhibition.jpg
        imageAltText: Museum visitors interacting with buttons on a label deck in an exhibit
        html: >
          <p>This moon guitar is exhibited in the museum’s traveling exhibition, <a href="https://www.amnh.org/exhibitions/traveling-the-silk-road" target="_blank">“Traveling the Silk Road: Ancient Pathway to the Modern World,”</a> which originated at the museum in 2009.</p>

  northwest:
    query: Regions CONTAINS NORTHWEST AND Region CONTAINS North America
    itemId: "E/ 2462"
    title: Northwest Coast Hall
    slides:
      - html: >
          <p>Beginning in 1896, the Museum’s anthropology collection was divided into different halls by geography.</p>
          <p>The first was the <a href="https://www.amnh.org/exhibitions/permanent/northwest-coast" target="_blank">Northwest Coast Hall</a> which displayed objects from Indigenous peoples of the Pacific Northwest.</p>
      - itemId: "E/ 2462"
        object: obj/content/haida/bracelet.obj # material file should be obj/content/haida/bracelet.obj.mtl
        html: >
          <p>One of these items is that has been exhibited is <a href="https://anthro.amnh.org/anthropology/databases/common/image_dup.cfm?catno=%20%20%20E%2F%202462" target="_blank">an engraved silver bracelet</a>. These types of bracelets became popular in Northwest Coast communities in the late 1800s. Click on the icon to interact with the object.</p>
      - image: img/content/northwest/bracelet_today.jpg
        imageAltText: Arms of women wearing decorative engraved bracelets
        text: And they are still worn today.

#################################
# Guide
#################################
# This app gives you guide the user between the different views of the data.
  # You can simply comment out this entire section if you want to let the user
  # simply explore freely.

guide:
  - text: The museum’s anthropology collection is over 530,000 objects with more objects added every year. Over half of those objects are digitized.
    changeLayout: randomSphere # you can automatically change the layout like this
  - text: Explore the objects by looking around with your mouse and using the arrow keys to move. Click an object to see its catalog information.
    # you can also include alternative text for touch or XR devices (XR support still in development)
    touchText: Explore the objects by touching and dragging and using the navigation circle to move. Tap an object to see its catalog information.
    xrText: Explore the objects by using the thumbsticks to move. Point and select an object to see its catalog information.
  - text: Let’s explore where objects were collected on a map.
  - changeLayout: geographyBars
    text: The objects in the anthropology collection come from around the world. Move around the map to see how many objects come from each country.
  - moveToLocation: # you can move the camera to a location based on normalized points between 0 and 1 (measured from top-left corner of bounds)
      x: 0.2
      y: 0.75
    text: Some countries are represented by many objects. <strong>Mexico</strong> is represented by the most objects — <strong>47,423</strong>!
  - text: A large number of objects might show that a collecting expedition went to that country or a private collection from that country was purchased or donated.
  - text: Next, let’s explore <em>when</em> these objects were collected.
  - changeLayout: timelineTunnel
    text: People have collected and donated objects to the museum throughout its 150-year history. Move through the time tunnel to see when objects were added to the collection.
  - text: Like in the map layout, a large number of objects in a year might show when a collecting expedition took place or private collection was purchased.
    moveToTime: 1930 # in timelineTunnel or timelineTracks view, you can jump to a year
  - text: A small number of objects in a year may be because of an inability to collect, a financial downturn, or even incomplete data.
    moveToTime: 1924
  - text: How does the collection look when organized by both geography and time?
  - changeLayout: timelineTracks
    text: This layout shows the collection organized by geography and time. Explore the racetracks, you can see even more patterns in the museum’s history of collecting.
  - text: Let’s look at one collecting expedition from 1901-1904 that added over 7,500 objects to the museum’s Asian Ethnography collection.
    moveToTime: 1901
  - showStory: laufer

#################################
# User interface
#################################
# You can mostly leave these alone, but update these values to customize the user interface

labels:
  # these are the labels of the years for the `timelineTunnel` and `timelineTracks` views
  yearFontSize: 24
  yearFontThickness: 4
  # these are the labels for each group in `timelineTracks` view
  groupFontSize: 16
  groupFontThickness: 1
  # these are the labels of the countries in the `geographyBars` view
  countryFontSize: 12
  countryFontThickness: 1

animation:
  startTransitionDuration: 5000 # The initial fade in duration
  transitionDuration: 3000 # The amount of time to transition between views
  componentTransitionDuration: 500 # How long components like labels and overlays should fade in/out
  zoomInTransitionDuration: 2000 # How long it takes ot zoom when user selects an item
  minAlpha: 0.0 # the transparency of inactive items (not visible by default)