Ecosyste.ms: Awesome

**Speculative Annotation** is a dynamic website and public art project by Library of Congress Innovator in Residence Courtney McClellan. The tool presents a unique mini collection of Free to Use items from the Library of Congress for students, teachers, and users of all ages to annotate through captions, drawings, and other types of markmaking. Working with curators at the Library and students and teachers in the classroom, McClellan developed Speculative Annotation to provide a way for students to speak back to history.

Speculative Annotation connects items from the past with the day-to-day experience of users. It was made with a K-12 audience in mind, with the hope that primary sources from the Library’s collection will be used by educators. The items are shared with contextual aids including curator annotations and links to additional resources for further research on the Library’s website.

The experimental application will premier at the Library of Congress in the summer of 2021 at https://labs.loc.gov/work/experiments/. We hope that other cultural heritage organizations will use this open source tool with their own materials to spark engagement and dialogue with historical objects.

Visit [Library of Congress Labs](https://labs.loc.gov/work/experiments/annotation/) for more information.

### Demo

[Test drive the application](https://nervous-gates-006218.netlify.app/)

The staging environment is currently hosted with [Netlify](https://www.netlify.com/), and builds are synced with Github pushes to https://github.com/adamjarling/loc-speculative-annotations `main` branch.

### Built With

- [React](https://reactjs.org/)
- [FabricJS](http://fabricjs.com/)
- [IIIF](https://iiif.io/)
- [OpenSeadragon](https://openseadragon.github.io/)
- [Chakra UI](https://chakra-ui.com/)

## Getting Started

To get a local copy up and running follow these simple steps.

### Prerequisites

You must be running a local copy of NodeJS and `npm` or `yarn` for package management. We'll use `yarn` in these examples:

### Installation

1. Clone the repo
```sh
git clone https://github.com/adamjarling/loc-speculative-annotations.git
```
2. Install NPM packages
```sh
yarn install
```

### Running the application locally

To run the application locally in your development environment:

```sh
yarn start
```

To run tests (coming soon...)

```sh
yarn test
```

### Styleguide

[View styleguide](https://www.figma.com/file/laNqMbfi7FSeHweqgyH8Jn/Speculative-Annotation-Style-Guide?node-id=0%3A1)

## Usage

### Source images

Source images are currently hosted locally and defined and imported in the following configuration file:

`src/services/loc-images.js`

An Work image file names should be its LOC `id`. Image files, thumbnails of images, and Curator annotation image files are located in:

```
src/images/loc-images
src/images/loc-images/thumbnails
src/images/curator-annotations
```

The application uses the OpenSeadragon Viewer to render images, so your source images can be a combination of locally hosted images (within the application), or externally hosted images (for example, served from a IIIF image server).

### Selecting items

When putting together the Speculative Annotation mini collection, the project team was careful to consider the ethics of annotation and what items would or would not be appropriate for public annotation, as well as what kinds of items would engage students. This includes issues of copyright (all items are free to use at the Library) but also concerns about defacement. We considered issues of culturally specific imagery, religious materials, and human figures, particularly black and brown bodies, minors and private citizens.

When adding your own images to your instance of the application, here are some questions to consider:
- Does this item depict civilians who did not agree to their picture being taken?
- Does this item depict minors?
- Does this item depict human figures, particularly black and brown bodies, that could be defaced or harmed through annotation?
- Was the item created for public consumption and by who?
- Have you considered how the culture depicted in the item or that created the item sees annotation?
- Does the item spark imagination and storytelling?
- Can the item stand on its own? How much context is required?

### IIIF Manifests

Application metadata is represented by a combination of local IIIF Presentation API 3.0 manifest files, and Library of Congress hosted IIIF manifest files. The organization of local files is as follows:

_Top level manifest:_
`public/iiif/speculative-annotations-manifest.json`

- Top level **Collection** type manifest resource which contains information about the Speculative Annotation works as a collection.
- Individual **Manifest** type manifests which each represent a Work, its metadata, annotations, containing LOC Collection, and more.
- Placeholder Library of Congress Collection manifests which contain metadata about a containing Collection for each Work.

The naming convention here is also cued off a Work's LOC `id`. Every Work image in the app should have a corresponding folder in:

`public/iiif/[LOC_WORK_ID_HERE]`

Every work image in the app should also be an object entry in the `public/iiif/speculative-annotations-manifest.json` file as well.

### Custom theme

If you'd like to update the UI with your own custom colors, fonts, etc. this is possible via Style Props and custom theming. This app uses the wonderful Chakra UI package, and see [Chakra UI Customize Theme](https://chakra-ui.com/docs/theming/customize-theme) for details.

### Testing

Currently only broad, high-level integration testing is supported via the Cypress.io testing library. To manually run tests, from the command line do:

```
yarn cypress:open
```

See all available application scripts and commands in the `package.json` file.

## Roadmap

See the [open issues](https://github.com/adamjarling/loc-speculative-annotations/issues) for a list of proposed features (and known issues).

## Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are **greatly appreciated**.

1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## License

Distributed under the MIT License. See `LICENSE` for more information.

## Contact

### Library of Congress Labs

Jaime Mears - Innovator in Residence Program Manager [email protected]

LC Labs - (https://labs.loc.gov) [email protected]

Courtney McClellan - Innovator in Residence - www.courtneymcclellan.com

### Developers / Designers

Adam J. Arling - UI Developer - [@adamjarling](https://github.com/adamjarling)

Jessica VU - UX Consultant

Olivia Graham - Grahpic Design Intern

## Acknowledgements

Remi Kalir PhD and Antero Garcia PhD
Emily Kirkpatrick and the National Council of Teachers of English
Kaleena Stasiak, Printmaker
Josh Hadro and the team at IIIF

The contributing staff of the Library of Congress:
Manuscript Division
Prints and Photographs Division
Hispanic Section
Near East Section
American Folklife Center
Performing Arts Division
Music Division
Serial and Government Publications
Rare Book Division
Geography and Maps Division
Professional Learning, Outreach & Initiatives Office
Motion Picture, Broadcasting & Recorded Sound
User Experience Design Section
Mission Platforms Section
Software Engineering Division

[contributors-shield]: https://img.shields.io/github/contributors/adamjarling/repo.svg?style=for-the-badge
[contributors-url]: https://github.com/adamjarling/repo/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/adamjarling/repo.svg?style=for-the-badge
[forks-url]: https://github.com/adamjarling/repo/network/members
[stars-shield]: https://img.shields.io/github/stars/adamjarling/repo.svg?style=for-the-badge
[stars-url]: https://github.com/adamjarling/repo/stargazers
[issues-shield]: https://img.shields.io/github/issues/adamjarling/repo.svg?style=for-the-badge
[issues-url]: https://github.com/adamjarling/repo/issues
[license-shield]: https://img.shields.io/github/license/adamjarling/repo.svg?style=for-the-badge
[license-url]: https://github.com/adamjarling/repo/blob/master/LICENSE.txt
[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555
[linkedin-url]: https://linkedin.com/in/adamjarling

Ecosyste.ms: Awesome

https://github.com/adamjarling/loc-speculative-annotations

Awesome Lists containing this project

README

Table of Contents