Creating 3D Scenes or Games with Three.js to Communicate Material Culture Diversity

[hawc2]

Programming Historian in English has received a proposal for a lesson, 'Communicating Material Culture Diversity by Creating 3D Online or Virtual Reality Scenes or Games with Three.js' by @tosca-har and @mathieuleclerc17.

I have circulated this proposal for feedback within the English team. We have considered this proposal for:

• Openness: we advocate for use of open source software, open programming languages and open datasets
• Global access: we serve a readership working with different operating systems and varying computational resources
• Multilingualism: we celebrate methodologies and tools that can be applied or adapted for use in multilingual research-contexts
• Sustainability: we're committed to publishing learning resources that can remain useful beyond present-day graphical user interfaces and current software versions

We are pleased to have invited @tosca-har to develop this Proposal into a Submission to be developed under the guidance of @carlonim as editor.

The Submission package should include:

• Lesson text (written in Markdown)
  • For guidance, we recommend Sarah Simpkin's lesson Getting Started with Markdown
• Figures: images / plots / graphs (if using)
• Data assets: codebooks, sample dataset (if using)

We ask @tosca-har to share their Submission package with our Publishing team by email, copying in @carlonim .

We've agreed a submission date of April. We ask @tosca-har to contact us if they need to revise this deadline.

When the Submission package is received, our Publishing team will process the new lesson materials, and prepare a Preview of the initial draft. They will post a comment in this Issue to provide the locations of all key files, as well as a link to the Preview where contributors can read the lesson as the draft progresses.

_If we have not received the Submission package by April, @carlonim will attempt to contact @tosca-har. If we do not receive any update, this Issue will be closed.

Our dedicated Ombudspersons are Ian Milligan (English), Silvia Gutiérrez De la Torre (español), Hélène Huet (français), and Luis Ferla (português) Please feel free to contact them at any time if you have concerns that you would like addressed by an impartial observer. Contacting the ombudspersons will have no impact on the outcome of any peer review.

[charlottejmc]

Hello @carlonim, @tosca-har and @mathieuleclerc17,

You can find the key files here:

• .md: /en/drafts/originals/creating-3d-scenes-games-threejs.md
• images: /images/creating-3d-scenes-games-threejs
• assets: /assets/creating-3d-scenes-games-threejs

You can review a preview of the lesson here:

• http://programminghistorian.github.io/ph-submissions/en/drafts/originals/creating-3d-scenes-games-threejs

---

I've updated the links to images within the lesson file so that they follow our liquid syntax:
{% include figure.html filename="file-name-1.png" alt="Visual description of figure image" caption="Figure 1. Caption text to display" %}

I have updated the image file names to follow our image naming convention, but there are still two important parts for you to fill in: the image 'alt-text' (Visual description of figure for visually impaired readers) and the caption. Please feel free to make these edits directly to the markdown file, or to write them to me in a comment (or via email: publishing.assistant[@]programminghistorian.org).

I also left out two images: scene.jpg and final_scene.png, because I could not see them in the markdown file. If you'd like to add them in though, please do let me know!

Thank you!

[anisa-hawes]

Hello Kristine @tosca-har and Mathieu @mathieuleclerc17,

What's happening now?

Your lesson has been moved to the next phase of our workflow which is Phase 2: Initial Edit.

In this Phase, your editor Massimiliano @carlonim will read your lesson, and provide some initial feedback. Massimiliano will post feedback and suggestions as a comment in this Issue, so that you can revise your draft in the following Phase 3: Revision 1.

%%{init: { 'logLevel': 'debug', 'theme': 'dark', 'themeVariables': {
              'cScale0': '#444444', 'cScaleLabel0': '#ffffff',
              'cScale1': '#882b4f', 'cScaleLabel1': '#ffffff',
              'cScale2': '#444444', 'cScaleLabel2': '#ffffff'
       } } }%%
timeline
Section Phase 1 <br> Submission
Who worked on this? : Publishing Assistant (@charlottejmc) 
All  Phase 1 tasks completed? : Yes
Section Phase 2 <br> Initial Edit
Who's working on this? : Editor (@carlonim)  
Expected completion date? : June 3
Section Phase 3 <br> Revision 1
Who's responsible? : Authors (@tosca-har + @mathieuleclerc17)
Expected timeframe? : ~30 days after feedback is received

Loading

Note: The Mermaid diagram above may not render on GitHub mobile. Please check in via desktop when you have a moment.

[tosca-har]

Hello Anissa Mathieu's GitHub is mathieuleclerc17 Forgive my ignorance but am I correct in thinking that when there are reviewer / editor comments I'll get notified through GitHub? Regards Kris Get Outlook for iOS<https://aka.ms/o0ukef>

…

________________________________ From: Anisa Hawes ***@***.***> Sent: Friday, May 3, 2024 4:22 AM To: programminghistorian/ph-submissions ***@***.***> Cc: Kristine Hardy ***@***.***>; Mention ***@***.***> Subject: Re: [programminghistorian/ph-submissions] Communicating Material Culture Diversity by Creating 3D Online or Virtual Reality Scenes or Games with Three.js (Issue #607) Hello Kristine @tosca-har<https://github.com/tosca-har> and Mathieu (Kristine, Please could you share Mathieu's GitHub handle with us?), What's happening now? Your lesson has been moved to the next phase of our workflow which is Phase 2: Initial Edit. In this Phase, your editor Massimiliano @carlonim<https://github.com/carlonim> will read your lesson, and provide some initial feedback. Massimiliano will post feedback and suggestions as a comment in this Issue, so that you can revise your draft in the following Phase 3: Revision 1. %%{init: { 'logLevel': 'debug', 'theme': 'dark', 'themeVariables': { 'cScale0': '#444444', 'cScaleLabel0': '#ffffff', 'cScale1': '#882b4f', 'cScaleLabel1': '#ffffff', 'cScale2': '#444444', 'cScaleLabel2': '#ffffff' } } }%% timeline Section Phase 1 <br> Submission Who worked on this? : Publishing Assistant ***@***.***) All Phase 1 tasks completed? : Yes Section Phase 2 <br> Initial Edit Who's working on this? : Editor ***@***.***) Expected completion date? : June 3 Section Phase 3 <br> Revision 1 Who's responsible? : Authors ***@***.*** + Mathieu) Expected timeframe? : ~30 days after feedback is received Note: The Mermaid diagram above may not render on GitHub mobile. Please check in via desktop when you have a moment. — Reply to this email directly, view it on GitHub<#607 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/ANVXZEFBQWM7ZA6D3JFSRY3ZAJ76JAVCNFSM6AAAAABE52Z67SVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAOJRGIZDAMRYGQ>. You are receiving this because you were mentioned.Message ID: ***@***.***>

[anisa-hawes]

Thank you, Kristine @tosca-har! I've now tagged Mathieu in my earlier comments.

You can configure your GitHub notifications by navigating to Settings (accessed from the menu which opens when you click on your profile avatar image in the upper right corner). Select Notifications and scroll down to define your Subscriptions. It sounds as though you want to receive notifications in the Participating, @mentions and custom category. Click on the grey button which reads: Notify me. This opens a small pop-up where you can select the channels via which you would like to receive notifications. Select the notification channels of your choice and click Save.

When receiving notifications in Participating, @mentions and custom category, you will be notified if anyone comments in this Issue (or any other Issues you have contributed to), or @mentions your name.

--

Massimiliano @carlonim will provide initial feedback as a comment in this Issue within the coming ~10 days. 🙂

[carlonim]

Dear @tosca-har and @mathieuleclerc17,
Here is my feedback for the initial edit. Thank you again for submitting this lesson, and sorry for the delay in sending you these observations.

I really enjoyed going through the lesson and trying out the code, both because the lesson is well constructed and gradually adds pieces of code, and because the website with the 3D models is an end result that many readers will appreciate.

Below are some general observations based on the criteria outlined in our editorial workflow. I have tried to link each observation to paragraphs of text so that you can better understand what I mean, but if anything is unclear, just let me know and I will be happy to give you more details! Also, these are proposals and suggestions, so we can certainly discuss each specific point and if/how to implement them.

Usability

• Lesson objectives and outcomes are clearly explained both in the introduction (§§1-7) and in the conclusions (§§173-4).
• Overall, the lesson has a clear structure and guides the reader through the entire learning process by providing clear headings that illustrate the individual steps (e.g., Adding the Information Panels and Maps and Adding the Jar Models).
• I have tried all the code and can confirm that it works perfectly. Unfortunately, I was not able to test the parts that include VR, since I do not have VR equipment, and the emulator suggested by the authors (the Chrome plugin Immersive Web Emulator) did not work for me (the authors themselves point out that compatibility is limited: see §90). But if necessary, I will try to find a way to test this part as well.
• The lesson covers a generous number of different aspects, including both 3D visualisation and VR implementation, as well as more interactive aspects, such as the development of the game. The authors have done a very good job of condensing all of this into a single Programming Historian (PH) lesson, just over the word limit (9,000 words). Also, the clear structure of the lesson allows the reader to easily skip sections that are marked as optional by the authors (see §88).
• However, I wonder if it would be better to avoid the VR and game-related parts altogether, in order to focus more on the simple 3D visualisation. This would allow the text to have a more limited word count (around 5,000 words) and would enable the authors to include some additional explanations of the code in the extra space (around 3,000 words). Currently, we have no PH lesson that deals specifically with 3D models, so it would make much sense for us to publish a first lesson where some key concepts in 3D (like mesh or texture) are explained (or where relevant external sources are cited). The authors could then consider publishing a second lesson with the PH, building on this first lesson and taking into account VR and/or the development of the puzzle.
• More explanations of the code would also allow readers to get a better sense of how they can personalise the code for their own purposes, for example by changing certain parameters or building their own scenes. The authors already point out this possibility of personalisation (§§70-71), and I think that going further in this direction would certainly be of great benefit to the readers.
• Finally, I was wondering if there is a way to cut the code partially. I see that in some cases the code snippets take up a large part of the relative section (for example, Adding Jar Selection to VR); perhaps the code could be interspersed with additional explanations? Sometimes, the code snippets include variables or constants that are defined for every single object on the scene, with only slight variations between the individual objects. Would it be possible to create custom classes? Or perhaps summarise the parameters in a table, give two or three examples, and let the readers fill in the parameters for the remaining objects (along the lines of §172)?

Sustainability

• The authors have already done a great job of clearly defining what tools are needed and what options are available to the reader. Perhaps a mention of the specific library version of Three.js used here would be helpful, although I am personally not aware of how often the library changes and breaks backward compatibility – the authors of the lesson probably know better.
• On more than one occasion, the authors rightly point out potential challenges or issues the readers might encounter (for example, when dealing with interactivity without VR) and propose specific workarounds with clear instructions (see §138). This is very positive, since readers are not confronted with unexpected problems that seem impossible to solve.

Accessibility

• All the software used or suggested by the authors is free, and most of it is also open source, which greatly broadens the potential audience for this lesson. Even when suggesting a specific tool, the authors provide alternatives where possible (for example, GitHub Pages or Vercel in §13).
• All images have both captions and alternative text.

Inclusivity

• I really appreciated the Ethics section. It helps the reader to contextualise the proposed task and to get a better idea of why some aspects of the site have been designed as they are. I would welcome even more comments not only on the potential risks of creating these 3D visualisations and interactive tools, but also on what is the best way (or one good way) to avoid these potential risks (as mentioned in the last sentence of §29: "For example it might be better to have objects returned to their place of origin, than a puzzle that features them being stolen or ‘collected’"). For example, what should the creator of such a webpage take into account? What can they do to inform users and help them understand the purpose of the website?
• Perhaps providing a general overview of which communities in Papua New Guinea will be covered in the website would help the reader to follow the lesson's instructions more effectively. Such an overview could be included in one of the introductory sections (or a new specific section could be devoted to it).

Difficulty

• At the moment, I would say that this lesson positions itself as an advanced one according to the PH criteria. The reader should already have a good knowledge of JavaScript and a little familiarity with 3D. Also, it is helpful to read the Three.js documentation before or during the lesson to better understand what certain pieces of code do.
• However, as previously suggested in the Usability section above, I believe that with just a few changes this lesson could be configured slightly differently, and could even become an intermediate lesson. While I believe that previous knowledge of JavaScript is necessary, I think that the inclusion of additional explanations of 3D concepts, as well as references to the specific classes and methods included in Three.js, could make this lesson more accessible to a wider audience and broaden the use of 3D in the Digital Humanities.

I also have additional feedback on specific points of the text. However, I prefer to start with these more general observations because I think the form of the text might change in the next phases. But as I said, if you prefer to have more details on any aspect (even which terms or code snippets I think could be the subject of additional definitions or explanations), I am more than happy to send them to you!

Thank you again for your submission and I look forward to hearing from you!

[anisa-hawes]

Hello Kristine @tosca-har and Mathieu @mathieuleclerc17,

What's happening now?

Your lesson has been moved to the next phase of our workflow which is Phase 3: Revision 1.

This phase is an opportunity for you to revise your draft in response to @carlonim's initial feedback.

Mathieu @mathieuleclerc17 I've sent you an invitation to join us as an Outside Collaborator here on GitHub. This will give you the 'write access' you'll need to edit your lesson directly. (Kristine already has access).

We ask authors to work on their own files with direct commits: we prefer you don't fork our repo, or use the Pull Request system to edit in ph-submissions. You can make direct commits to your file here: /en/drafts/originals/communicating-diversity-in-3D-and-VR.md. @charlottejmc and I can help if you encounter any practical problems!

When you and Massimiliano are happy with the revised draft, we will move forward to Phase 4: Open Peer Review.

%%{init: { 'logLevel': 'debug', 'theme': 'dark', 'themeVariables': {
              'cScale0': '#444444', 'cScaleLabel0': '#ffffff',
              'cScale1': '#882b4f', 'cScaleLabel1': '#ffffff',
              'cScale2': '#444444', 'cScaleLabel2': '#ffffff'
       } } }%%
timeline
Section Phase 2 <br> Initial Edit
Who worked on this? : Editor (@carlonim) 
All  Phase 2 tasks completed? : Yes
Section Phase 3 <br> Revision 1
Who's working on this? : Authors (@tosca-har + @mathieuleclerc17)  
Expected completion date? : July 14
Section Phase 4 <br> Open Peer Review
Who's responsible? : Reviewers (TBC) 
Expected timeframe? : ~60 days after request is accepted

Loading

Note: The Mermaid diagram above may not render on GitHub mobile. Please check in via desktop when you have a moment.

[carlonim]

Dear @tosca-har and @mathieuleclerc17, I am checking-in to ask how you are getting on with your revisions? Please let us know if you think you'll need more time, or if you are on-track to share your new draft with me at the end of this week/beginning of next. Also, I am always available for any question or to discuss alternative revision suggestions. Thank you very much!

[tosca-har]

Hello @carlonim. @mathieuleclerc17 and I should have our initial attempt at the revisions done by the 14th. I was away at a field school with unreliable internet for June so apologise for the delay. We have removed the VR aspect but kept the game aspect (so I've changed the title). User feedback continually suggested that placing the jars on the torus was very difficult in the non-VR version, so I've modified the code so that a correct match is also detected if the mouse is hovering over the correct torus at the end of the jar drag. I want to avoid using classes (despite it being better practice), because I think it's more beginner friendly without them, but I have made constructor-like functions for the creation of the jars to try and reduce the code repetition. However, I've introduced the function in 3 steps so I'm not sure it saves words. We will have the changes uploaded by the 14th.
Regards
Kris

[carlonim]

Hello @tosca-har and @mathieuleclerc17. Thank you very much for your update! I'm glad to hear that work is proceeding well on your side! No worries, I just wanted to hear if you had any questions or new suggestions for the revision. Your approach seems sound to me, and I also agree with the title change. Just one small question: I believe that in the current title:
Communicating Material Culture Diversity by Creating 3D Online or Games with Three.js
a word is missing, probably something like Scenes after 3D Online—or alternatively the or should be dropped. so that it becomes 3D Online Games. Or should I interpret the title differently?
Thank you again!

[carlonim]

Another quick note on the title: as suggested by @anisa-hawes, another possibility would be to swap the order of the two halves of the title, and have something like Creating 3D Scenes or Games with Three.js to Communicate Material Culture Diversity. This would support readers to better understand the focus of the lesson when browsing the Programming Historian directory. What do you think about this option?

[tosca-har]

I like the "Creating 3D Scenes or Games with Three.js to Communicate Material Culture Diversity" title.

[anisa-hawes]

Thank you for confirming that you're happy with this suggested adjustment to the lesson's title Kristine @tosca-har. I agree with Massimiliano @carlonim that foregrounding the verb Creating will help readers know what the lesson's focus is.

Thanks to @charlottejmc for taking care of renaming the various files + directories, and adjusting components of the metadata to reflect the new lesson title 👐🏼

For convenience, I'm re-sharing the locations of your key files, (reflecting the revised file paths):

• .md: /en/drafts/originals/creating-3d-scenes-games-threejs.md
• images: /images/creating-3d-scenes-games-threejs
• assets: /assets/creating-3d-scenes-games-threejs

You can review a preview of the lesson here:

• http://programminghistorian.github.io/ph-submissions/en/drafts/originals/creating-3d-scenes-games-threejs

Thanks all! ✨

[tosca-har]

Hello Massimiliano @carlonim
I've edited the markdown file. It is now less than 8000 words, so let me know if you want us to write more on any of the areas. I've added 5 figures -which has messed up the figure names (sorry! @charlottejmc - at the moment I think they all link and work but the file names will be misleading, so I'm not sure whether to change them and risk messing things up).

[charlottejmc]

Thanks for letting me know, @tosca-har – I've renamed the images so they are all in sequential order from 1-17.

[carlonim]

Thank you very much Kristine @tosca-har and Mathieu @mathieuleclerc17! I will have a look at the lesson next week (July 15-21) and let you know.
Thanks again!

[carlonim]

Hello Kristine @tosca-har and Mathieu @mathieuleclerc17, I am still going through your revisions, and will post my feedback by the end of this week ~28th July. Thank you for your patience!

[carlonim]

Thank you Kristine @tosca-har and Mathieu @mathieuleclerc17 for submitting your revised version! Here are some brief comments. They are followed by a list of minor corrections, which mostly deal with typos.

If possible, could I ask you to make these additional changes in the next few days, say by August 6th? This would be greatly appreciated as it would allow us to move more quickly into the peer review phase. But let me know if you think you need more time. I have also marked all my suggested corrections/edits as to-do items, so you can check them off as you go, and keep track of what you are editing more easily.

First, thanks for the additional explanatory text you added between the code snippets. I also find the additional images in §§ 69, 71, 73 very helpful, since they give an overview of what 3D models consist of. And thanks also for creating the createModel() function (§86), which allows to avoid some of the repetition in the previous code.

I really appreciate how the Ethics section (§§ 29-32), which was already very interesting, has been improved with even more material and ideas.

• Regarding the general organization of the lesson, I would like to ask if you could reorganize/rename the headings so that some sections become sub-sections of others. This way, the Table of Contents would have a smaller number of top-level steps, which would make it easier to read.

• While testing the code, I had a small problem with the snippet in § 145. It seems that you declare the variable truesite twice, which causes an error in the JavaScript interpreter (at least in my case). Maybe you should remove truesite from the first line? The code would be:

let jars, torus, unmoveable;
let truesite = null;
let selectedObject = null;

• Also, a question about § 153: I did not understand exactly what changes are brought about by the rewritten version of the function onClick( event ), since – at least for me – the website is behaving the same as before. Could you please explain me the difference again? You could also add a few words to § 153, if you think it would be useful. Thank you!

Smaller corrections

• Sometimes three.js is written as Three.js. Capitalization could be standardized to either of these forms, as you prefer.

§ 1

• add abbreviation (PNG) in brackets after Papua New Guinea, since the abbreviation is used afterwards (e.g. § 4)

§ 3

• include models > include 3D models

§ 4

• occurred at least partially, > occurred, at least partially,
• Petrequin and Petrequin (2006) > Pétrequin and Pétrequin (2006)

§ 5

• to see if they have been placed > to see if it has been placed

§ 7

• MacOS > macOS

§ 8

• MacOS > macOS

§ 10

• Embed the link to NodeJS directly into the text (i.e., [NodeJS](https://nodejs.org))

§ 11

• Github > GitHub

§ 12

• github > GitHub
• Embed the link to Vercel directly into the text (i.e., [Vercel](https://vercel.com))

§ 13

• library > the library
• from javascript script > from JavaScript script

§ 14

• I would add a short introductory sentence to illustrate what the reader will be accomplishing by following the next steps (e.g., "To set up the initial files and directories for your project").

§ 22

• Wasn't the index.html file already saved before creating the main.css file?

§ 30

• results in the some of the brilliance of some of the potteries being under-represented > results in the brilliance of some of the potteries being under-represented

§ 31

• Oruc, 2020 > Oruç, 2020
• D'Andra et al. 2022 > D'Andrea et al. 2022

§ 32

• whether an scenes or especially puzzles > whether scenes or especially puzzles

§ 34

• orginally > originally

§ 45

• Should "torus" be replaced by its plural form "tori" (which you also use in § 124)? This also applies to some occurrences of the term "torus" in §§ 115, 116.

§ 50

• its important > it is important

§ 60

• Afinity Designer > Affinity Designer
• Powerpoint > PowerPoint
• .visbile > .visible

§ 87

• The second code block is not rendered appropriately, probably because single quotes are used instead of backticks to delimit it (before and after with)

§ 95

• It would be useful to have a link to the examples of the different types of camera controls on the Three.js website.
• You could briefly mention that, when using a mouse, the act of moving around can be performed by clicking and dragging, and that scrolling will zoom in and out.

§ 116

• plane > panel

§ 118

• takes, position (x and z) co-ordinates, and the relevant gallery > takes position (x and z) co-ordinates and the relevant gallery

§ 125

• in the > In the

§ 149

• its > it is
• to place in the > to place it in the

§ 156

• It seems to me that "REPLACE" in this line could be removed (the action is already expressed by "change the texture to the intro2.jpg"), or the line could be rephrased differently.

[tosca-har]

Sorry @carlonim We somehow missed this (usually there are notifying emails but for some reason this didn't come through) and I've just seen this now. I'll work on it right away and try and get them to you in the next few days.

[anisa-hawes]

Thank you, Kristine @tosca-har and Mathieu @mathieuleclerc17 !

It would be very helpful to us if you could check off the suggestions/questions in Massimiliano's list as you work through/respond to them.

[tosca-har]

@carlonim @anisa-hawes @charlottejmc I think we have addressed everything. I'm a bit unsure of the sub-headings- they seem OK in the preview but I can't see the table of contents so I'm not sure how that looks. I also moved the pottery and ethics section up- and I think that works OK, but let me know if it ruins the flow or is too much text before people start actually writing code. As a side note I'm wondering if the use of tick boxes upset the ANU email system, because it is odd that that email never came through to either of us while the last comment did. I am sorry for the delay I should have checked the site sooner.

[anisa-hawes]

Thank you, Kristine @tosca-har.

We are grateful for your work on this. The table of contents is automatically generated with the snippet {% include toc.html %} in the Markdown. Although it isn't displayed there, we can review it here in the Preview: https://programminghistorian.github.io/ph-submissions/en/drafts/originals/creating-3d-scenes-games-threejs.

I'm sorry that the previous notification didn't reach you - it is odd. I remember that you configured your notification settings very carefully, so I am a bit confused about what has happened. Please don't worry though - we have had a quiet August here at PH, and we are all back in touch now 🙂

Next step will be for @carlonim to re-read the lesson and advise if it is ready to move onwards to Phase 4. I'm sure Massimiliano will be happy to share some reflections on how the adjusted sub-headings feel too.

[carlonim]

Dear Kristine @tosca-har and Mathieu @mathieuleclerc17, thank you so much for your edits! 🙂 No worries, there might have been some technical issue due to the to-do lists. In case I need to use them again, I will make sure you receive a separate message / notification too.
I will now re-read the lesson and let you know. I expect to have more time towards the weekend, so my feedback should reach you by Tuesday, September 17th, if it is ok for you.
Thank you again!

[carlonim]

Thank you Kristine @tosca-har and Mathieu @mathieuleclerc17 for your corrections! I have checked the text and can confirm that all the changes have been applied correctly. There are only a few (very small) typos, which I list in the next comment – if you could quickly edit your lesson and apply these corrections, it would be great! Also, let me know if you think that any of the corrections should not be applied.
Once you have updated the file, we will send out the peer review requests and keep you updated. Many thanks again!

[carlonim]

• § 7: While the use of the abbreviation PNG makes the body of the text more concise and readable, I would suggest using the full form (Papua New Guinea) in the heading. Potential readers who are browsing through the table of contents may not understand the meaning of PNG or may confuse it with the graphics format (Portable Network Graphic).
• § 59: .visble --> .visible
• In the three places listed below, the adjective annoymous is used. If I understand correctly (i.e. it refers to a function without a name), this is a typo for anonymous (just n and o should be swapped).
  • § 88
  • § 90
  • § 138
• § 95: scence -> scene
• § 112: I think that the question mark could be avoided, since it is an indirect question that depends on "consider". So the text could be changed to: Also consider if the puzzle is based on memory or logic.
• § 145: within in > within

[tosca-har]

@carlonim thank you for the edits- I've made the changes- I've left out the "Also"- You can add it in if you want. I think I originally wanted to say that I tried to make this game not just memory based, but with clues to the correct jar from the colour (forming technique) and decoration, but I thought that was too tangential/ irrelevant.

[anisa-hawes]

Hello Kristine @tosca-har and Mathieu @mathieuleclerc17 ,

What's happening now?

Your lesson has been moved to the next phase of our workflow which is Phase 4: Open Peer Review.

This phase is an opportunity for you to hear feedback from peers in the community.

Massimiliano @carlonim will invite two reviewers to read your lesson, test your code, and provide constructive feedback. In the spirit of openness, reviews will be posted as comments in this issue (unless you specifically request a closed review).

After both reviews, Massimiliano will summarise the suggestions to clarify your priorities in Phase 5: Revision 2.

%%{init: { 'logLevel': 'debug', 'theme': 'dark', 'themeVariables': {
              'cScale0': '#444444', 'cScaleLabel0': '#ffffff',
              'cScale1': '#882b4f', 'cScaleLabel1': '#ffffff',
              'cScale2': '#444444', 'cScaleLabel2': '#ffffff'
       } } }%%
timeline
Section Phase 3 <br> Revision 1
Who worked on this? : Authors (@tosca-har + @mathieuleclerc17)
All  Phase 3 tasks completed? : Yes
Section Phase 4 <br> Open Peer Review
Who's working on this? : Reviewers (@loko58 + @jlinker81)
Expected completion date? : ~60 days after request is accepted
Section Phase 5 <br> Revision 2
Who's responsible? : Authors (@tosca-har + @mathieuleclerc17)
Expected timeframe? : ~30 days after editor's summary

Loading

Note: The Mermaid diagram above may not render on GitHub mobile. Please check in via desktop when you have a moment.

[carlonim]

Open Peer Review

During Phases 2 and 3, I provided initial feedback on this lesson, then worked with Kristine @tosca-har and Mathieu @mathieuleclerc17 to complete a first round of revisions.

In Phase 4 Open Peer Review, we invite feedback from others in our community.

Welcome Steffen Bauer @loko58 and Jessica C. Linker @jlinker81. By participating in this peer review process, you are contributing to the creation of a useful and sustainable technical resource for the whole community. Thank you.

Please read the lesson, test the code, and post your review as a comment in this issue by January 22.

Reviewer Guidelines:

• https://programminghistorian.org/en/reviewer-guidelines

A preview of the lesson:

• http://programminghistorian.github.io/ph-submissions/en/drafts/originals/creating-3d-scenes-games-threejs

--
Notes:

• All participants in this discussion are advised to read and be guided by our shared Code of Conduct.
• Members of the wider community may also choose to contribute reviews.
• All participants must adhere to our anti-harassment policy:

Anti-Harassment Policy

This is a statement of the Programming Historian's principles and sets expectations for the tone and style of all correspondence between reviewers, authors, editors, and contributors to our public forums.

Programming Historian in English is dedicated to providing an open scholarly environment that offers community participants the freedom to thoroughly scrutinize ideas, to ask questions, make suggestions, or request clarification, but also provides a harassment-free space for all contributors to the project, regardless of gender, gender identity and expression, sexual orientation, disability, physical appearance, body size, race, age or religion, or technical experience. We do not tolerate harassment or ad hominem attacks of community participants in any form. Participants violating these rules may be expelled from the community at the discretion of the editorial board. If anyone witnesses or feels they have been the victim of the above described activity, please contact our ombudsperson Dr Ian Milligan. Thank you for helping us to create a safe space.

[jlinker81]

General Comments

January 20, 2025 – I unfortunately have not been able to complete this tutorial because I have been unable to get the .glb files on Github to render locally on my computer. This review therefore tests the tutorial to that point and generally comments on the tutorial as a whole. I would be happy to update my review if a fix could be provided to me.
I used the following software to test this tutorial: Visual Studio Code ver. 1.96.4 (which I downloaded per recommendations), Windows Powershell (Win 10 version), Google Chrome, and (initially) Node.js v12.18.4 before updating to v22.13.0. It may be worth including additional documentation about compatible software versions. As for hardware, I tested this on a VR-ready Lenovo Legion I usually use for 3D/VR development.

As someone who teaches students how to build 3D scenes with the Unity Engine, I was pleased to see a lesson that combined rendering a scene with Three.js with humanistic discussion of cultural heritage/archaeological objects. I likewise appreciated that the exercise instructions included reflections upon ethical use of 3D assets representing cultural objects and the communities themselves.

I was never clear while reading whether this tutorial was aimed at beginners or more advanced users; to some extent, I think additional explanation is warranted at various points regardless, as individuals who may come to this lesson with, say, some familiarity with Javascript, may not understand the basics of 3D models/modeling or coding that would require manipulation of objects within 3D space. This tutorial often assumes that each step will be completed with little frustration, because there’s no prompt to guide the user to resources or solutions should a step fail.
Below I identify some issues that I hope you will consider addressing.

Advice

Torus/tori: Because I am a 3D modeler, I knew what this refers to, but I’m not sure everyone would, and the first time the term is used it is not defined. It was defined later in the lesson; while understanding what this is wasn’t vital to proceeding with the lesson at that point, I think it may be worth complementing this first mention with an image of the object’s geometry, or by briefly defining this in the introductory paragraph. Students who are anxious about technology will sometimes give up if they are confronted with multiple unfamiliar terms at the outset of a lesson.

Refining language to be more specific may also help here. For example, in the introduction, the language “vessel is matched to the community” could be updated to read, more specifically, “a 3D model of a vessel is matched to the aesthetics of its community of origin” and “background colour will change” to “background colour of [model?] will change.” I assume this meant that the texture/color of the 3D vessel would change, but realize it could refer to the background of the scene, or something else entirely.

3D models vs. 2D images: In the paragraph that begins “Web models and digital games” I feel there is a missed opportunity to explain what 3D models can offer a practitioner that is different from 2D images, either in terms of introducing interactivity in novel ways to a program, else as cultural heritage records, or whatever is most important to you as the author. The reason why I bring this up is because the type of puzzle matching you propose could also be done with photographs of vessels. I do believe 3D models can offer something different and meaningful – but why not stake this out here?

Other 3D technologies and tools: You summarize the difference between Three.js and other 3D software/technology. Regarding the ability to post a product to the web -- The Unity Engine (for example) has the ability to package a scene as WebGL, which then can be run on the web on a domain or locally on the computer in-browser. Having done this before, I could make the argument that this process could be easier than building out code for Three.js. Even though one could code a scene entirely in C#, Unity provides is a WYSIWYG element to arranging scenes, black boxed coding for behaviors, and code-free pipelines (which are relatively new) for a range of functionality. I think I would try to shift framing this section not as “Three.js is easier than engines” to what three.js has to offer in terms of this pedagogical exercise or specific implementation. There are also code-free drag and drop options for arranging 3D models online not mentioned in this section, such as FrameVR, that would allow students to arrange models and graphics to think about the archaeological and cultural aspects of this lesson, but would not allow them to implement the matching algorithm.

SketchFab Models: You discuss this later in the tutorial, but model size matters and almost all of the cultural heritage scans on SketchFab would probably require editing in MeshLab or Blender to make them suitable for web applications because of the obscene amount of polygons they use – I think it would be helpful to recommend polygon count and resources for reducing it here. I assume this was included so that users could start arranging scenes with ready-made models post-tutorial, but just a note here to say that I don’t think enough is explained about the code (which seems to rely on certain fixed points specific to the PNG map and the vessels) for users to recreate a similar scene with models from SketchFab. Something to think about here in terms of the framing.

Lesson Goals: I liked the lesson goals related to Three.js functionality, but I thought there could be more said here about the lesson goals related to the puzzle matching, either in terms of implementing it or using it. For example, what are they learning about conditional statements (that may or may not be specific to manipulating objects in XYZ space)? Are there any learning goals that can be enumerated related to the ceramics, or making ethical choices about using 3D technology to depict cultural objects?

Ethics: You say: “The models used in this project, were created with Computer Aided Design (CAD) by the authors (who are not of PNG heritage) and are intended to be symbolic rather than realistic.” I’m glad that this was stated that you not from Papua New Guinea, and that you drew models from scratch with CAD, so these are not heritage models. You convey that there are some issues with copyright of objects/decoration/models. I think this level of transparency is good.
You suggest that it is good to seek permission from communities when doing this kind of work, but you don’t include evidence that you did this yourselves. In the spirit of Data Feminism, why not talk about this, particularly to provide a model about how to go about doing it? Additionally, if you are reconstructing objects somewhat generically because of these copyright issues, could we have a bit of information about how you made choices about what to include or not include? These are interpretative acts that bear explanation, and I also think it could help users who are making similar choices about cultural heritage objects being used in contexts like this.

Terminals: The instructions indicate that one should test to see if node.js is working by inputting “node -v” in the terminal. Please be explicit that you mean the Powershell terminal rather than the node.js terminal screen. There is nothing in the instructions to suggest what the user should do if “node -v” doesn’t work; it would help to have a line or two suggesting some common things to check.

Copy-pasting into text editors: Because I don’t know what level of user this is aimed at, I think it might be worth explaining that code copy-pasted into VSC will display color encoding if valid. This could help debug problems caused by not fully copying the large chunks of script.

Pasting, generally: Much of this tutorial involves copy-pasting large chunks of script into the text editor in various parts of the script. I thought this could be improved generally by including more explanation of what the script did and why it was being pasted into a particular location (the head vs. the body vs. within an init function, so on). For example, when you prompt the user to create index.html – why not explain what a doctype declaration is? What the “head” is and what it usually contains? What the “body” is and what it usually contains? Or if this is superfluous with another PH exercise, could you link out to that so the user has reference? There’s also no explanation of what a cascading style sheet is, what an init function does, etc. As I was following directions I couldn’t help but think that the user doesn’t really understand exactly what the code does. While I don’t think the user needs to know how to script this program from scratch at the end of the lesson, she also has no real understanding of how to navigate or alter the script.

Another thought – maybe include commented “paste here after step X” within the initial paste of the index.html so it is easier to paste code into the right location. Some explanation of what the copy-pasted section does could go in the comments too.

Difficulty rendering local scene: I had some difficulty rendering the scene in my browser the first time the tutorial asked me to do this. I followed the directions here: “Make sure that the command line of your terminal/shell indicates that you are in the myscene folder (…myscene %). In VSC, Terminal > New Terminal will give you a terminal.” Here, I thought it may be worth pointing out that the “Terminal” option may be in a hamburger/(…) menu, as mine was. I typed in “npx serve” as directed and got the following error:

“npx.ps1 cannot be loaded because running scripts is disabled on this system. For more information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170.”

This is when I updated node.js to the latest version, which did not resolve the problem. I later had to change permission settings within Powershell. This strikes me as an error that may commonly occur, particularly if the user has set up the software particularly to do this tutorial. I think it would be useful to include some common errors and how to resolve them here.
The command “npx serve” then worked properly in the VSC terminal, but after being prompted by the VSC terminal to go to http://localhost:3000/ I could not see anything but a black screen. After being frustrated by that for a few minutes, I tried to get it to work from Powershell rather than from the VSC terminal – this generated localhost: 54990 with the same response. What ultimately seemed to work was re-saving the index.html file, re-opening VSC and generating a third local host port in VSC’s terminal. I suspect index.html had some unchanged saves and that’s what was causing the issue, so I would recommend reminding the user to save the file (or noting that saving the file at X point will allow the scene to render) and including some instructions about specifying a port if the default port is for some reason in use.

Out-of-the-blue-backgrounds: The tutorial says: “This background will be peach (0xf7d382). To specify colours you can use the colour hex code after ‘0x’.” Later in the tutorial we change the code so the background is that hex color, but because my background in the original rendering was black, I was initially confused by what this referred to. I recommend changing the language to read “Later in this tutorial, we will use a hex code to update the color of your default background (black) to be peach. This is expressed in hex as ….”

Ctrl-C: At some point in the tutorial it states that you can close a terminal with ctrl-c – I tested this at this point (assuming that the unexperienced user might also do this) and didn’t reopen the terminal, but the next time I was instructed to refresh the localhost URL, I got an error. Now, I realized it was because I had closed the terminal with ctrl-c and I needed to input “npx serve” again – but you might want to include a note to the user about needing to input “npx serve” in a new terminal if you ever close your terminal. New users will not know what to do in these instances.

Spheres: The user eventually realizes why we’re adding a line of colored spheres when they get deeper into the tutorial, but it may be worth explaining that we’re setting up a GUI menu.

Text on images is very small: Has this tutorial been tested on a range of resolutions? I successfully imported the image files with text on them. The text from the imported graphics is almost too small to read, especially on the source card. I realize this would require some new code, but it may be worth writing something that allows the text to scale with the resolution of one’s screen.

Instructions about how to import models: The tutorial tells you to download a “models” folder, but links you to a “gltf” folder. This “gltf” folder lives in a “models” folder, and that hierarchy is actually important based on the calls in the code – please tell users that the hierarchy matters and they should recreate it exactly.

At this point, however, I could not get any imported .glb model to display despite going over the instructions several times, though I had no issues with importing the 2D images or rendering native Three.js geometry (the spheres). I spent several hours trying to figure out what was wrong but couldn’t determine the issue. I could not proceed with the tutorial at this point.

Last Thoughts

I read through the end of the tutorial and determined that the remaining instructions were presented similarly to what I had already executed. My ultimate concern is that I do not know that any new user (or even intermediate user) would understand any of this code, having pasted it in, even if they successfully completed the lesson. The parts I most appreciated were the moments in which the user was prompted to check the updated scene to see a change based on pasted-in code. If the user isn’t empowered to recreate a scene of their own from scratch because of this tutorial (which may not be the goal) I would recommend more cases that involve, for example, updating variables, so that users can see how changing aspects of the code can change the scene. I’ve already said this, but additional explanation of what pasted-in code does would also help the user gain this knowledge.

I started coding in three.js a few years ago because I was intrigued by an eleven-line script that produced a simple scene. I thought this would be useful for teaching coding mechanics because students could play with lighting and moving shapes while only needing to understand what a few lines did. I wonder if it’s worth having a brief tutorial of lighting, colors, shapes that can be rendered, etc. in a simpler environment before launching into how this works with this lengthy bit of code.

I otherwise wholeheartedly commend what is being done here – I think modeling how one might use Three.js to explore art forms in other cultures, particularly with caveats about how to do so responsibly, is an excellent way to teach humanistic applications of this technology.

[tosca-har]

@jlinker81 I'm not sure why the glb files aren't rendering- although I did a run through on a PC when I wrote the tutorial- I primarily use a Mac, so trouble shooting on a PC is more difficult for me.

If you drop a glb https://gltf-viewer.donmccurdy.com does it work? That would test if the files have downloaded correctly.
If you look at the web page png-vessels.vercel.app, do you see vessels? That would test if there is a memory issue (unlikely).
To test if the page is seeing the glb files- the console log should say if it can't see a glb file. For chrome that's (View > Developer > Javascript console).
The other possible issue is the loading of the Draco compressor which comes which is part of the three add ons- and I've had issues before when I've changed three.js versions, . I'm not sure of the error message that comes up if that is the problem and I'm not sure of how to test that that is the problem. One possible solution -which I remember considering previously was to have the glb files not Draco compressed- as this makes them bigger but I think there may be less things that can go wrong.
If you can tell me what the Javascript console is saying then I may be able to work out what's going on.

[carlonim]

@jlinker81 Thank you so much for your detailed review! And thanks to @tosca-har for already providing feedback on these technical aspects. As @jlinker81 has already informed me, she will be able to give you further feedback based on your instructions towards the end of the week due to lecturing duties.
Thanks again for your contribution to the Programming Historian!

[jlinker81]

@tosca-har, the models don't open with that link. And if I try to open them with Microsoft's native 3D viewer, it suggests there's something wrong with them. Ditto if I try to import them into Blender. (The error is "Bad gtlF: Json error" when I try.) What software did you use to make these again? But as @carlonim says, I'll have more time to mess around with this later in the week.

[tosca-har]

@jlinker81 @carlonim @charlottejmc Hello Jessica
The models were created and saved (as compressed files) from Blender (although this was over a year ago -so an older version of Blender than the current). I have downloaded one model (Adzera.glb) from the PH GitHub site and it works for me in the donmccurdy linked viewer- I have to wait a few second but that is on my student uni PC (which is very basic) , so it's not a Mac/PC thing. @charlottejmc I can't work out a way to download all the models folder from the PH GitHub in one click (is this just me?) its downloading the link not the folder. Do you think we can have the models folder compressed and downloadable? and have instructions to extract the folder - this can be annoying as different operating systems etc, but I don't think students want to download each model. I shall see if I can put a compressed folder up.
I suspect it's an issue with the model downloads. However, there is still an argument to be made for using uncompressed gtlf files as the Draco loader is more finicky than the gtlf loader and I will try and get the files un Draco compressed and see if they remain small enough for loading- they should as its more the VR version that was sensitive to file size.

[anisa-hawes]

Dear Kristine @tosca-har,

We can put the models together inside a .zip folder so that once the lesson is published a single click will initiate download. The download behaviours don't work in this way on our work-in-progress repository/via the lesson Preview.

Would you like one .zip containing all the files found here /assets/creating-3d-scenes-games-threejs/models/gltf? Let us know how you want the files organised (in one set, or several sets), and we can prepare this for you.